[MERGE] Prettier docs with kid

[John Arbash Meinel]

Aaron Bentley wrote:
> Hi all,
> 
> I've updated my patch to generate HTML documents with kid.  This version
> - Supplies Makefile.pretty
> - Handles HTML entities like  
> - Provides links to "Documentation index", "Other versions" and "Wiki".
> - Does not strip HTML anchors (<a name=...>), instead forcing their
>   color to black.
> - Does not force file extensions to '.html'.
> 
> This seems mergeable, or at we can run it to produce docs for bzr 0.12
> 
> I went with separate makefiles because they each provide different ways
> of producing the same targets.  (docs/foo.htm and html_docs/foo.htm)
> 
> Aaron

Some quick comments:

1) They do look nice. And they fit much better with the rest of the bzr
site.

2) To me it makes more sense to use 'make pretty-html-docs' rather than
have an entirely separate Makefile. But if there are technical reasons
why that is difficult, I'm not opposed to it.

3) rst2prettyhtml is not PEP8 compliant. Is that a big deal??? I'm not sure.

4) I actually greatly prefer '.html' as the extension. We went with .htm
in the other set because Alexander uses them as the Windows default
extension. I suppose there isn't much we can do, though, since the
internal hyperlinks point to .htm. I may have said something different
in the past. Though my main concern was having a .htm *and* a .html with
the same name.

4) Most of the pages look as I would expect. But for some reason
'centralized_workflow.htm' has very different headings. I realize I
enabled '.. sectnum::', which may be the difference, I don't know
exactly what rule you use to decide what should be fixed black. It may
also be because I added a table of contents, which means every index is
indeed referenced. Maybe it is because the "CLASS" is "toc-backref" so
you can click on the TOC entry to jump there and then click on a title
to jump back to the TOC.

It may not make sense everwhere, but section numbering and automatic
table of contents are things that I think we should use more.


...

+#!/usr/bin/env python2.4
+import errno
+import os
+from StringIO import StringIO
+import sys
+
+from docutils.core import publish_file
+from docutils.parsers import rst
+from elementtree.ElementTree import XML
+from elementtree import HTMLTreeBuilder
+import kid

^- You have a raw 'import kid' here, as well as 'docutils'. It is
probably better to do some sort of try/except so that we can give nice
errors to the user about why they need kid for this, but don't need it
to run bzr itself.

Going along with that, you seem to assume 'elementtree' is available,
but it may only be bundled with bzrlib, and we don't require docutils
except for this sort of thing.

5) It seems a little weird to hard-code the paths to all of the content
files (like the javascript files, etc). Especially since if we change
the name of the website (it's happened before :), then all the links
stop working. And it is weird to me to depend on an external javascript,
etc, especially when working in a local directory. But since this is
really only meant to work as part of the website, I can certainly
overlook that.

6) I think you've addressed anything else I've commented on. So probably
you can convince me to just accept what you have and merge it.

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/20061107/1e065a42/attachment.pgp