[MERGE] Prettier docs with kid

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

John Arbash Meinel wrote:

> 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.

Okay, I figured out how to make it work as a separate set of targets.

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

Okay, I've updated it.

> 4) I actually greatly prefer '.html' as the extension. 

Me too, but I'd rather leave that as a separate merge.

> 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. 

It is because adding a toc turns each heading into a hyperlink, and I
was only trying to force anchors to black.  I have added a style rule to
make "toc-backref" headings look like normal headings (no underline, black).

> ^- 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.

Okay, I've added nice dependency failure messages for docutils, kid and
elementtree.

> 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.

Basically, I don't want to get version skew, and I don't understand what
all the different stylesheets do.  And there's all the additional
images, too.  Besides, cool URLs don't change:
http://www.w3.org/Provider/Style/URI

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFU+bL0F+nu1YWqI0RAvvlAJ9iYwV7Mo58wUEi3J7ZaJHfPELtuwCdFxz7
ZDR69i2QcuFFgOfC5i0pe6I=
=ZWDC
-----END PGP SIGNATURE-----
-------------- next part --------------
A non-text attachment was scrubbed...
Name: kid-docs-2.patch
Type: text/x-patch
Size: 168458 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20061109/74e5f58d/attachment.bin