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 :|
3:43 a.m.
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
5:54 a.m.
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 :|
8:21 a.m.
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 :|
10:49 a.m.
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(a)redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
10:59 a.m.
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 :|
11:30 a.m.
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(a)redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
6059
days inactive
6060
days old
6 comments
3 participants
participants (3)
-
Daniel P. Berrange -
Daniel Veillard -
Richard W.M. Jones