[Libvir] PATCH: Re-structuring the libvirt.org website content
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-libvirt.h... http://berrange.fedorapeople.org/libvirt/website-demo/html/libvirt-virterror... 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 :|
Have we lost the hvsupport page? It exists if I go to the URL directly but I can't see it listed in the left hand index. Also we seem to have lost some CSS from that page. Note that docs/libvirt.css should contain styles for table.top_table near the bottom of the file, but those are now missing from http://berrange.fedorapeople.org/libvirt/website-demo/libvirt.css Rich. -- Richard Jones, Emerging Technologies, Red Hat http://et.redhat.com/~rjones virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into Xen guests. http://et.redhat.com/~rjones/virt-p2v
On Mon, Apr 21, 2008 at 09:43:03AM +0100, Richard W.M. Jones wrote:
Have we lost the hvsupport page? It exists if I go to the URL directly but I can't see it listed in the left hand index.
Ah yes - I missed that in the sitemap - I'll add it back at the "drivers" section.
Also we seem to have lost some CSS from that page. Note that docs/libvirt.css should contain styles for table.top_table near the bottom of the file, but those are now missing from
I'll fix that too Dan. -- |: 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 :|
On Mon, Apr 21, 2008 at 11:54:59AM +0100, Daniel P. Berrange wrote:
On Mon, Apr 21, 2008 at 09:43:03AM +0100, Richard W.M. Jones wrote:
Have we lost the hvsupport page? It exists if I go to the URL directly but I can't see it listed in the left hand index.
Ah yes - I missed that in the sitemap - I'll add it back at the "drivers" section.
I changed my mind & thought it better to put it alongside the API docs, since its highly relevant info when looking at the APIs. http://berrange.fedorapeople.org/libvirt/website-demo/hvsupport.html Dan. -- |: 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 :|
On Sun, Apr 20, 2008 at 07:47:08PM +0100, Daniel P. Berrange wrote: In a nutshell, fantastic, I like this a lot !
- 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...
We need to add the CIM provider for libvirt http://libvirt.org/CIM/ CC'ing the CIM mailing-list as they will be impacted by this, an update of their site would make sense to keep the harmony.
- Linked to the new wiki site, and added seemless integration betweeen the wiki navigation & styling, and the main site.
adding the Wiki is important, thanks, but I don't see the integration, c.f. http://wiki.libvirt.org/page/Main_Page , what did I missed ?
- 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.
I like the design, just a couple of nits, the fonts are a bit small and when going to the API page it looks a bit bizarre.
Again, if all this is too much to take in, just go straight to the sitemap page on the demo site and click around...
For the API page, I would be a bit conservative, first because I hate when URLs for documentation break, second because it's part of the search index under the API, and as such the entries from the PHP or the database would have to be shuffled if you break the pages. Another thing to verify is that the indexer which fills up the database on libvirt.org/xmlsoft.org for the search works well with the new set of pages, I think that's okay but will have to be tested once we change the main site, still I like this a lot :-) Daniel -- Red Hat Virtualization group http://redhat.com/virtualization/ Daniel Veillard | virtualization library http://libvirt.org/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
On Mon, Apr 21, 2008 at 11:49:27AM -0400, Daniel Veillard wrote:
On Sun, Apr 20, 2008 at 07:47:08PM +0100, Daniel P. Berrange wrote:
In a nutshell, fantastic, I like this a lot !
- 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...
We need to add the CIM provider for libvirt http://libvirt.org/CIM/ CC'ing the CIM mailing-list as they will be impacted by this, an update of their site would make sense to keep the harmony.
Yes, I've already added this to the related links page along with links to all the language bindings. I'll also link the 'CIM provider' in the front page bullet list.
- Linked to the new wiki site, and added seemless integration betweeen the wiki navigation & styling, and the main site.
adding the Wiki is important, thanks, but I don't see the integration, c.f. http://wiki.libvirt.org/page/Main_Page , what did I missed ?
I changed the default site style, but if you're logged into the admin account you might need to change your account preferences to use the new skin - http://wiki.libvirt.org/page/Special:Preferences Select the 'Libvirt' skin.
- 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.
I like the design, just a couple of nits, the fonts are a bit small and when going to the API page it looks a bit bizarre.
Not sure what you mean about the API pages ? They're using the same style as the rest of the site. The only other style change there was that the table of contents puts everything within one <pre> intead of multiple to get rid of the repeated boxes in the TOC of the current page. The fonts display the same size as the current site when I compare them. Or do you want them bigger than the current site ?
Again, if all this is too much to take in, just go straight to the sitemap page on the demo site and click around...
For the API page, I would be a bit conservative, first because I hate when URLs for documentation break, second because it's part of the search index under the API, and as such the entries from the PHP or the database would have to be shuffled if you break the pages.
The API pages are still using the same URLs as before. If we were to split it out into groups by virConnect/Domain/Network/Storage, then I'd suggest still keeping the same existing URLs for compatability, and use that page to link to the group pages. So if someone stored the URL they'd still get a valid page, and no 404's Dan. -- |: 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 :|
Oops, sorry resent, I forgot to Cc: the CIM list, On Sun, Apr 20, 2008 at 07:47:08PM +0100, Daniel P. Berrange wrote: In a nutshell, fantastic, I like this a lot !
- 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...
We need to add the CIM provider for libvirt http://libvirt.org/CIM/ CC'ing the CIM mailing-list as they will be impacted by this, an update of their site would make sense to keep the harmony.
- Linked to the new wiki site, and added seemless integration betweeen the wiki navigation & styling, and the main site.
adding the Wiki is important, thanks, but I don't see the integration, c.f. http://wiki.libvirt.org/page/Main_Page , what did I missed ?
- 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.
I like the design, just a couple of nits, the fonts are a bit small and when going to the API page it looks a bit bizarre.
Again, if all this is too much to take in, just go straight to the sitemap page on the demo site and click around...
For the API page, I would be a bit conservative, first because I hate when URLs for documentation break, second because it's part of the search index under the API, and as such the entries from the PHP or the database would have to be shuffled if you break the pages. Another thing to verify is that the indexer which fills up the database on libvirt.org/xmlsoft.org for the search works well with the new set of pages, I think that's okay but will have to be tested once we change the main site, still I like this a lot :-) Daniel -- Red Hat Virtualization group http://redhat.com/virtualization/ Daniel Veillard | virtualization library http://libvirt.org/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
participants (3)
-
Daniel P. Berrange -
Daniel Veillard -
Richard W.M. Jones