1:47 p.m.
The current way we structure and manage the website for libvirt.org is
becoming (has become) unsustainable as we add more features which in turn
require more documentation.
The first problem is all content is in a single huge file docs/libvir.html,
from which each individual page is then extracted. When adding new content
I find myself spending more time just scrolling up & down the file trying
to find my place, than actually writing content. The obvious change is
to split this file up, so that it is one file per page on the website.
With some clever XSL we can still keep the benefit of automatically merging
the content with the shared HTML layout / navigation.
The second problem is that the navigation is completely flat, giving rise
to the increasingly long set of the links down the left hand side. This
is discouraging the addition of new pages with the result too much content
is lumped together in the same page, and making it harder to navigate the
site.
I started to write some more content for the serial device format, but gave
up and decided to spent the time this weekend attempting to address these
two problems to create a more developer & user friendly website, and then
writing some more general content for the site too. The patch is rather
unsuprisingly enourmous so I am not attaching it to this mail. Instead I
have uploaded it to
http://berrange.fedorapeople.org/libvirt/libvirt-website.patch
Reading the patch isn't too interesting - you're probably more interested
in the end result, so I've also uploaded a demo copy showing the proposed
new style and site navigation:
http://berrange.fedorapeople.org/libvirt/website-demo/index.html
The 'sitemap' page is a good place to start if you want to see how it all
fits together.
NB, this demo of the site structure will be removed after a few days
because we don't want to disrupt the google index for the main site, so
if you're reading this message from the archives just go to the main
http://libvirt.org site to see how it all evolved...
The changes to the build process / source structure are as follows:
- The giant docs/libvir.html file is now removed, and all its content is
placed into individual files named XXX.html.in where XXX is the name
of the page as viewed on the site.
The markup in the XXX.html.in files consists soley of the actual page
content inside the <body> tag. There is no <head> data. There is no
navigation or style markup in these XXX.html.in files. They are the
pure content of each page. This makes writing new content very clear
and straightforward.
- There is now a hiearchical navigation structure, with 10 pages at the
top level, and the rest nested below these levels. The master structure
for the site is defined in the file sitemap.html.in which is also
exposed directly on the site
http://berrange.fedorapeople.org/libvirt/website-demo/sitemap.html
- The page.xsl file reads the site structure from the sitemap.html.in file
and builds up a context-sensitive menu on the left hand site of every
page. Sub-levels in the hierarchy will be automatically expanded as
neccessary.
- Content from the XXX.html.in files is processed by the site.xsl transform
to add in the page navigation and metadata. The site.xsl transform calls
to the page.xsl file to pull in navigation. The resulting generated pages
are named XXX.html as before.
- The newapi.xsl file has been updated to make use of page.xsl to pull
in the navigation menu to the API reference pages.
- The ChangeLog.xsl file has been updated to make use of page.xsl to
pull in the navigation menu
Adding a new page is now very straightforward:
- Create a new file XXX.html.in in the docs/ directory and write the
content you desire
- Edit the docs/sitemap.html.in file and add a link to the new page at
the appropriate place in the site hierarchy - this automagically deals
with the left hand context nav menu.
- Type 'make web' to generate the XXX.html page with navigation and
update navigation in the other pages.
Finally the content changes / additions. First of all, all existing content
from the site is still there - it has merely been re-arranged in places.
- The content on the front page is refreshed to give a succinct summary
of what libvirt is about, inspired by the oVirt front page:
http://berrange.fedorapeople.org/libvirt/website-demo/index.html
- There is a page for every hypervisor driver, which is intended to
describe the requirements of the driver, and provide example XML
documents for the driver. I have added some basic content for
the Xen and QEMU drivers - other drivers still need docs
http://berrange.fedorapeople.org/libvirt/website-demo/drvxen.html
http://berrange.fedorapeople.org/libvirt/website-demo/drvqemu.html
- There is a page for every XML format used by libvirt. I've mostly
copied content from the existing format.html and storage.html pages
into these new pages unchanged, and added some info on the virtual
network XML. All of thee pages need some major revision though, since
the existing content is severely out of date for domains, and
capabilities.
http://berrange.fedorapeople.org/libvirt/website-demo/formatdomain.html
http://berrange.fedorapeople.org/libvirt/website-demo/formatnetwork.html
http://berrange.fedorapeople.org/libvirt/website-demo/formatstorage.html
http://berrange.fedorapeople.org/libvirt/website-demo/formatcaps.html
- There is a page for every major subsystem in libvirt, describing the
concepts behind that part of the API. There are pages for domains,
networks, storage and node devices. Again we have a need for more content
in this area to give developers a high level overview of our API concepts.
Much of this information exists in email threads from the time at which
we designed the APIs (in particular true for storage & network APIs).
http://berrange.fedorapeople.org/libvirt/website-demo/intro.html
http://berrange.fedorapeople.org/libvirt/website-demo/archdomain.html
http://berrange.fedorapeople.org/libvirt/website-demo/archnetwork.html
http://berrange.fedorapeople.org/libvirt/website-demo/archstorage.html
- There are pages for language bindings, though there is only content
for python
http://berrange.fedorapeople.org/libvirt/website-demo/bindings.html
http://berrange.fedorapeople.org/libvirt/website-demo/python.html
- There are pages focusing on deployment issues such as building / install
of libvirt, deploying on windows, remote management config, authentication
config and URI formats. This content is all unchanged from existing
pages
http://berrange.fedorapeople.org/libvirt/website-demo/uri.html
http://berrange.fedorapeople.org/libvirt/website-demo/remote.html
http://berrange.fedorapeople.org/libvirt/website-demo/auth.html
http://berrange.fedorapeople.org/libvirt/website-demo/windows.html
- The API docs are of course seemlessly included in the site structure
http://berrange.fedorapeople.org/libvirt/website-demo/html/index.html
http://berrange.fedorapeople.org/libvirt/website-demo/html/libvirt-libvir...
http://berrange.fedorapeople.org/libvirt/website-demo/html/libvirt-virter...
IMHO, we could do with re-structuring these APIs docs though. The main
libvirt-libvirt.html page is getting too large to deal with. It would
be better for developers if we could split up into sections for each
of the major public objects, virConnectPtr, virDomainPtr, virNetworkPtr
virStoragePoolPtr and virStorageVolPtr and their associated APIs.
This shouldn't be too hard todo with a little tweaking of the API docs
generator.
- The related links are now on a page of their own, since the list on
the left hand menu was getting too large.
http://berrange.fedorapeople.org/libvirt/website-demo/relatedlinks.html
- There is a page describing all applications using libvirt as their API
http://berrange.fedorapeople.org/libvirt/website-demo/apps.html
Shout if you have more applications you want added to this page...
- Expanded content a little wrt to bug reporting and mailing lists
http://berrange.fedorapeople.org/libvirt/website-demo/bugs.html
http://berrange.fedorapeople.org/libvirt/website-demo/contact.html
- Linked to the new wiki site, and added seemless integration betweeen
the wiki navigation & styling, and the main site.
- There is a new updated CSS graphic design - I can't take credit for
that - it is from mockups done by one of the Red Hat designers.
Again, if all this is too much to take in, just go straight to the sitemap
page on the demo site and click around...
http://berrange.fedorapeople.org/libvirt/website-demo/sitemap.html
The patch for all this is at
http://berrange.fedorapeople.org/libvirt/libvirt-website.patch
The giant and fairly meaningless diffstat is:
ChangeLog.xsl | 72
FAQ.html | 225 +-
FAQ.html.in | 144 +
Makefile.am | 49
apps.html | 179 +
apps.html.in | 108
archdomain.html | 99
archdomain.html.in | 5
architecture.html | 142 +
architecture.html.in | 101
archnetwork.html | 99
archnetwork.html.in | 5
archnode.html | 99
archnode.html.in | 5
archstorage.html | 119 +
archstorage.html.in | 30
auth.html | 198 +
auth.html.in | 183 +
bindings.html | 109
bindings.html.in | 24
bugs.html | 141 +
bugs.html.in | 82
contact.html | 91
contact.html.in | 37
deployment.html | 131 +
deployment.html.in | 46
devhelp/libvirt-virterror.html | 6
docs.html | 85
docs.html.in | 5
downloads.html | 142 +
downloads.html.in | 89
drivers.html | 146 +
drivers.html.in | 27
drvlxc.html | 108
drvlxc.html.in | 5
drvopenvz.html | 108
drvopenvz.html.in | 5
drvqemu.html | 187 +
drvqemu.html.in | 97
drvremote.html | 108
drvremote.html.in | 5
drvtest.html | 108
drvtest.html.in | 5
drvxen.html | 303 ++
drvxen.html.in | 221 +
errors.html | 141 -
errors.html.in | 83
format.html | 450 +---
format.html.in | 243 ++
formatcaps.html | 165 +
formatcaps.html.in | 70
formatdomain.html | 115 +
formatdomain.html.in | 18
formatnetwork.html | 175 +
formatnetwork.html.in | 93
formatnode.html | 102
formatnode.html.in | 5
formatstorage.html | 331 ++
formatstorage.html.in | 237 ++
generic.css | 74
html/book1.html | 3
html/index.html | 5
html/libvirt-conf.html | 44
html/libvirt-lib.html | 3
html/libvirt-libvirt.html | 961 +++-----
html/libvirt-virterror.html | 173 -
hvsupport.html | 1031 +++++----
hvsupport.html.in | 597 +++++
index.html | 238 --
index.html.in | 68
intro.html | 132 +
intro.html.in | 46
libvir.html | 4596 -----------------------------------------
libvirt-api.xml | 6
libvirt-header-bg.png |binary
libvirt-header-logo.png |binary
libvirt-net-logical.fig | 159 +
libvirt-net-logical.png |binary
libvirt-net-physical.fig | 139 +
libvirt-net-physical.png |binary
libvirt-refs.xml | 7
libvirt.css | 345 +--
main.css | 2
newapi.xsl | 380 +--
news.html | 462 ++--
news.html.in | 607 +++++
page.xsl | 94
python.html | 161 +
python.html.in | 71
relatedlinks.html | 114 +
relatedlinks.html.in | 55
remote.html | 851 +++++--
remote.html.in | 893 +++++++
site.xsl | 407 ---
sitemap.html | 279 ++
sitemap.html.in | 220 +
storage.html | 963 +++-----
storage.html.in | 354 +++
uri.html | 349 ++-
uri.html.in | 295 ++
windows.html | 303 +-
windows.html.in | 239 ++
103 files changed, 13910 insertions(+), 8327 deletions(-)
Regards,
Daniel.
--
|: Red Hat, Engineering, Boston -o- http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|