[libvirt] Docs team task: Update main docs.html page with index of all pages

[Justin Clift]

Hi Anthony,

(Following up from previous email, but CC'ing the libvirt team this time
as some of the guys might have input/ideas/etc.)

I'm thinking the very best thing you can do is get our "Docs" landing
page under control for the main site:

 http://libvirt.org/docs.html

It's very blank, relying on people to realise that everything is accessible
on the left hand menu bar instead. :(

What it should contain is an index to all of the main documentation
pieces, so people can click directly from there.

Some sort of menu structure will be needed (up to you, try things out).

The way the website works, is that it's actually part of the libvirt source
code.  The "docs" directory in the source code is effectively the website.

When people update the docs directory in the git repository, there's a
cronjob on the libvirt.org server that rebuilds the live website.

So, first things first, you'll need to make sure you have the "xhtml1-dtds"
package installed.  It's in the main CentOS repositories, so yum should
know it automatically.

Then you'll need to get the main libvirt source code from git:

  $ git clone git://libvirt.org/libvirt.git
  Cloning into libvirt...
  remote: Counting objects: 50501, done.
  remote: Compressing objects: 100% (8276/8276), done.
  remote: Total 50501 (delta 42262), reused 50237 (delta 42087)
  Receiving objects: 100% (50501/50501), 52.13 MiB | 165 KiB/s, done.
  Resolving deltas: 100% (42262/42262), done.

  $ ls -la
  total 0
  drwxr-xr-x   3 user  staff   102  8 Jan 21:47 .
  drwxr-xr-x@ 22 user  staff   748  8 Jan 21:47 ..
  drwxr-xr-x  65 user  staff  2210  8 Jan 21:55 libvirt

(For me, on the opposite side of the world to the main libvirt.org server,
this takes a while.  Several minutes.  Subsequent operations are much
faster.)

Then change into the newly created "libvirt" subdirectory, and run the
"autogen.sh" command.  This prepares the entire libvirt source code for
compiling locally, including the website docs (which you'll need).

  $ ./autogen.sh
  (this will configure itself if all the needed utils are installed, or it might
  barf if somethings missing.  It should proactively let you know if there's
  else that needs installing)

Once the autogen.sh has finished, run "make".  If you have a multi-core
processor, run it as a parallel make using the -j option:

  $ make -j 5

Parallel makes are a *bunch* faster than just using a single core.  The #
to use is the number of cores in the box, plus one.  (ie use -j 3 on a dual
core, use -j 9 on a 8 core box, etc)

If you open your browser, there should be in "index.html" file in the docs
directory. Open that.  Voila, it's the website. :)

So, the file you need to update is the docs/docs.html.in one.  When you
make changes to it, run the "make" command again.  That'll process it,
converting it from docs.html.in, to docs.html.

As you're trying things out and getting it right, feel free to copy the
generated output to some temporary spot on the web then post the URL
for comment/feedback/suggestions/etc.  (I do this fairly often too)

When you reckon it's all good and ready for inclusion, I'll give you the steps
for generating a patch file and posting it.  It's pretty simple. :)

How's that so far?

Regards and best wishes,

Justin Clift