[MERGE] Pretty docs with Kid

[John Arbash Meinel]

Aaron Bentley wrote:
> Hi all,
> 
> I've just implemented a way of generating output that matches the wiki.
> 
> It works by taking the docutils HTML output and running it through a Kid
> template.  Sample output is here:
> 
> http://code.aaronbentley.com/configuration.html
> 
> Kid templates can be XHTML, and so the kid template for this output
> looks like the front page of the wiki, when viewed directly in a browser.
> 
> Post-processing is done to
> 1. turn local links to 'foo.htm' into links to 'foo.html'.  This allows
> the pretty pages to coexist with the normal pages
> 2. strip anchor tags, because the bazaar-vcs.org stylesheet is broken
> and treats all <a> tags as links, even when they're <a name='foo>foo</a>.
> 3. remove some inappropriate links
> 4. change the 'Search Bazaar' box to 'Search Wiki'.
> 
> Aaron

1) This means you depend on 'kid', right? I realize it is a separate
tool, and not core bzr, but it is another dependency.

2) Please don't strip all the <a> tags. We may need to update the
stylesheet, but it is *really* nice to reference a specific subsection.
http://doc.bazaar-vcs.org/bzr-0.11/configuration.htm#location-of-configuration-file

3) What inappropriate links?

The reason the links are '.htm' is because that is what is generated. I
assume because Alexander is more used to Windows development where .htm
is frequently preferred to .html. But if you look at the website: 'make
html-docs' generates:
http://doc.bazaar-vcs.org/bzr-0.11/configuration.htm

Also, this looks pretty bad:
+   def fixlink(attrib):
+      attrib = dict(attrib)
+      attrib['href'] = attrib['href'] + 'l'
+      return attrib

Since it assumes everything ends in '.htm' if you had one that was
'.html' you would get in pretty big trouble.

I really like that the output looks the same as the rest of the
documentation, so I'm happy with most of the result. (Especially since
we seem to keep forgetting to put default.css into the right directory,
though I emailed Martin about it).

I also think the Wiki css is probably nicer than our customized css in
general. We probably should copy it across, so that standalone
documentation gets the same css. (Especially since Alexander bundles the
documentation with his Windows Installer).

John
=:->

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060929/9e7096c6/attachment.pgp