PATCH: Re-structuring the libvirt.org website content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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.html
     http://berrange.fedorapeople.org/libvirt/website-demo/html/libvirt-virterror.html

    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 :|

--
Libvir-list mailing list
Libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list

[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]