[libvirt] Docs team task: Update main docs.html page with index of all pages
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
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello, On 01/08/11 12:00, Justin Clift wrote: [...]
I'm thinking the very best thing you can do is get our "Docs" landing page under control for the main site:
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
Right. I've been clicking through libvirt.org (= killing time) and ... how about to make it ala 'site map'. - --- SNIP --- Documentation Compiling ~ how-to compile libvirt; all you wanted to know about libvirt compilation and installation Deployment ~ deploying libvirt into production enviroment Architecture ~ how's libvirt structured? API concepts? Right here! XML Format ~ how's data stored within libvirt Drivers ~ what is and what is not supported by libvirt API reference ~ any serious libvirt integrator should read this one Language bindings ~ how to bind libvirt with C/C++, PHP, Ruby and some others Internals ~ how doest libvirt work under the hood Development guide ~ do you want to contribute to libvirt? Then this is mandatory for you Virsh commands ~ virsh command reference not only for command line junkies - --- SNIP --- + add Justin's text how to contribute to documentation, although it might be better to group such topic(dev'n contribution) at one place. So, link to such place instead? I know it's written very lightly and informal, jokingly, way. May be even a bit annoying. Well, I've been just thinking. Actually, I came up with these within minute(s). But back to the point. I would go with very very simple. No romances, no long texts. But perhaps I'm just simple person whom couldn't think of better way. Take it as my $0.02USD and I hope in better, and more creative, ideas than this one. :) 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.
[...]
Why not to include all of that at that page or ... somewhere, if not already? Have a nice day, Zdenek - -- Zdenek Styblik Net/Linux admin OS TurnovFree.net email: stybla@turnovfree.net jabber: stybla@jabber.turnovfree.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk0siAgACgkQ8MreUbSH7immxwCgovjJW7YZJnzwkyv6jqMUGgGJ uXQAoNTqd1G1VtWT8xVwIKuqynUrW6EA =TyKB -----END PGP SIGNATURE-----
On 12/01/2011, at 3:40 AM, Zdenek Styblik wrote: <snip>
Why not to include all of that at that page or ... somewhere, if not already?
Yeah, it probably would be better on a page somewhere. Feel like killing time writing a new page for the docs with that info? (maybe rewriting it to be less casual tone) :)
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 01/11/11 17:49, Justin Clift wrote:
On 12/01/2011, at 3:40 AM, Zdenek Styblik wrote: <snip>
Why not to include all of that at that page or ... somewhere, if not already?
Yeah, it probably would be better on a page somewhere.
Feel like killing time writing a new page for the docs with that info? (maybe rewriting it to be less casual tone) :)
Umm which part do you mean? Top, bottom ... all of it/suggested??? Z. - -- Zdenek Styblik Net/Linux admin OS TurnovFree.net email: stybla@turnovfree.net jabber: stybla@jabber.turnovfree.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk0sj2UACgkQ8MreUbSH7il0rgCcDBdw520X/NkY2bW7yoHRKFHA 2hEAn0PIxnLxiM5OkC7hn2ueJPumRuAJ =J+tk -----END PGP SIGNATURE-----
On 12/01/2011, at 4:12 AM, Zdenek Styblik wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 01/11/11 17:49, Justin Clift wrote:
On 12/01/2011, at 3:40 AM, Zdenek Styblik wrote: <snip>
Why not to include all of that at that page or ... somewhere, if not already?
Yeah, it probably would be better on a page somewhere.
Feel like killing time writing a new page for the docs with that info? (maybe rewriting it to be less casual tone) :)
Umm which part do you mean? Top, bottom ... all of it/suggested???
I'm thinking the steps on how to update the documentation itself. It's the kind of info that anyone updating the documentation would need to know. ?
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 01/11/11 19:12, Justin Clift wrote:
I'm thinking the steps on how to update the documentation itself. It's the kind of info that anyone updating the documentation would need to know.
?
Justin, I don't want to promise anything here. I've already promised my soul to Laine and I have one or two ideas of mine own on my mind right now. I can look at it, I can try it, it might take me 5-30minutes, might take day ... but when it's going to be, I can't tell. I just don't like promising things I'm not sure to deliver. Thus, for others [Anthony]. If you have an idea, get an idea, or anything. Don't wait for me, just do it. I hope that made some sense, Zdenek PS: I will surely keep it at my ToDo list. - -- Zdenek Styblik Net/Linux admin OS TurnovFree.net email: stybla@turnovfree.net jabber: stybla@jabber.turnovfree.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk0sql8ACgkQ8MreUbSH7innsQCdFiOTLwwP8Wd9WjnOXE8pNNFj OPgAn06EAJFbtYyb3gdoyuFWy08EN7L6 =7Zbo -----END PGP SIGNATURE-----
On 12/01/2011, at 6:07 AM, Zdenek Styblik wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 01/11/11 19:12, Justin Clift wrote:
I'm thinking the steps on how to update the documentation itself. It's the kind of info that anyone updating the documentation would need to know.
?
Justin, I don't want to promise anything here. I've already promised my soul to Laine and I have one or two ideas of mine own on my mind right now. I can look at it, I can try it, it might take me 5-30minutes, might take day ... but when it's going to be, I can't tell. I just don't like promising things I'm not sure to deliver. Thus, for others [Anthony]. If you have an idea, get an idea, or anything. Don't wait for me, just do it.
I hope that made some sense, Zdenek
PS: I will surely keep it at my ToDo list.
It's ok. I think it's a good idea, and was just trying to get someone other than me to do it. :)
On Tue, Jan 11, 2011 at 05:40:40PM +0100, Zdenek Styblik wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hello,
On 01/08/11 12:00, Justin Clift wrote: [...]
I'm thinking the very best thing you can do is get our "Docs" landing page under control for the main site:
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).
Right. I've been clicking through libvirt.org (= killing time) and ... how about to make it ala 'site map'.
- --- SNIP --- Documentation Compiling ~ how-to compile libvirt; all you wanted to know about libvirt compilation and installation Deployment ~ deploying libvirt into production enviroment Architecture ~ how's libvirt structured? API concepts? Right here! XML Format ~ how's data stored within libvirt Drivers ~ what is and what is not supported by libvirt API reference ~ any serious libvirt integrator should read this one Language bindings ~ how to bind libvirt with C/C++, PHP, Ruby and some others Internals ~ how doest libvirt work under the hood Development guide ~ do you want to contribute to libvirt? Then this is mandatory for you Virsh commands ~ virsh command reference not only for command line junkies - --- SNIP ---
This sounds like just a subset of what's already present in http://libvirt.org/sitemap.html It would be trivial to write some XSL to auto-generate docs.html from the subset of the sitemap.html content that is relevant. Daniel
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 01/11/11 19:18, Daniel P. Berrange wrote:
On Tue, Jan 11, 2011 at 05:40:40PM +0100, Zdenek Styblik wrote:
This sounds like just a subset of what's already present in
http://libvirt.org/sitemap.html
It would be trivial to write some XSL to auto-generate docs.html from the subset of the sitemap.html content that is relevant.
Daniel
Heh, great. Yeah, the idea was inspired by sitemap, although I haven't read it thoroughly [sitemap]. I also wanted to suggest some kind of parser, but I was afraid of look like parser-ill-person, although that might be just the case :) Ok, I've tried, it didn't go well and so much for idea ... back up to the tree(joking). Regards, Zdenek - -- Zdenek Styblik Net/Linux admin OS TurnovFree.net email: stybla@turnovfree.net jabber: stybla@jabber.turnovfree.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk0soksACgkQ8MreUbSH7inUWQCglPSOIJfhjrp4WfFZPJ9RkEpF VP8An2ojjrcRf6QDyWu1q7ER956dQbB/ =Bt4p -----END PGP SIGNATURE-----
On 12/01/2011, at 5:32 AM, Zdenek Styblik wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 01/11/11 19:18, Daniel P. Berrange wrote:
On Tue, Jan 11, 2011 at 05:40:40PM +0100, Zdenek Styblik wrote:
This sounds like just a subset of what's already present in
http://libvirt.org/sitemap.html
It would be trivial to write some XSL to auto-generate docs.html from the subset of the sitemap.html content that is relevant.
Daniel
Heh, great. Yeah, the idea was inspired by sitemap, although I haven't read it thoroughly [sitemap].
Hmmm, the Sitemap page does look like the kind of thing that could go there pretty easily. Anthony, do you know XSL at all?
participants (3)
-
Daniel P. Berrange -
Justin Clift -
Zdenek Styblik