Conversion of HTML docs to .rst

[p-static]

Following the conversion of the text-based docs to reStructuredText, it would make sense for consistency's sake to convert all the HTML-based documentation as well. This would also make the HTML docs more useful for people browsing through the source on the command line.

There's one sticking point before I start working on this: URLs. We want to have links in the documents such that they work as expected in HTML, and do something useful in any other format we convert the docs to. There are a lot of ways we could go with this:

• Have relative links that point to the rST versions of the docs. This is probably the least useful choice, because the HTML pages wouldn't work right.

• Have relative links that point to the HTML versions of the docs. (This is what they do now.) Downside is that somebody looking at the rST version of the doc wouldn't actually be directed to a useful resource, and the links wouldn't work if the HTML version hadn't been generated yet.

• Do some voodoo with the doc generation and convert the links. I'm not sure how much voodoo this would require; I think rST has some basic #define-style support for string substitution, but I'd have to try it out before knowing for sure that this option is feasible.

• Have absolute links pointing to the latest version of the HTML doc in Trac's VCS viewer. This is slightly hackish, and means that users viewing an outdated version of the documentation won't see anything useful by default, but it also gives us useful links in any format that we choose to use.

No matter which option we choose, it's probably unavoidable that generated docs will have to be committed to source control. :( Links directly into Trac's VCS viewer are used heavily, and these ones are probably widely distributed - we should avoid breaking them if possible. (This is why people don't usually store user-facing documents in the VCS and distribute them from there :)

[gdt]

It seems that the voodoo option is best; I'm surprised rST doesn't already support this as it seems like an obvious thing to want to do.

I don't understand why generated docs have to be committed; that's usually necessary only when the tools to generate them are so painful to deal with that users of the VCS should be spared the trouble because that's worse than the pain of having to commit generated files.

[zooko]

Here's a cool fact: trac will automatically render .rst files for you when viewed through trac, like this:

​http://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/configuration.rst

I believe github does something similar. I don't know about launchpad.

I think this means that relative links to .rst docs are the right answer. That makes it work for browsing with "less" locally and browsing with a web browser on trac/github, which are the two most important current use cases. In the future perhaps a clever .rst -> .html renderer could rewrite the links.

[p-static]

Oh, excellent! Yeah, if we get HTML rendering for free like that, then direct links are perfect. :D

[p-static]

add rST versions of the existing HTML docs (and also delete install.html, since it's unused)

[p-static]

replace HTML docs with versions generated from rST

[p-static]

The attached patches should be it for this bug. I separated it into two parts; it's up to you whether you want to use the second one, and keep generated HTML docs in the tree (would keep links from breaking), or just delete the HTML docs.

If we do want to keep the HTML docs in the tree, I should point out that they can be regenerated with rst2html from the python docutils library. It goes something like this:

rst2html < about.rst > about.html

[marlowe]

Recommend implementing html-rst-conversion.patch. I recommend deleting the HTML docs. We could create a README in the docs directory which would contain the instructions listed in comment 5 if they want generate the HTML files.

[zooko@…]

In 299e8ad5795d3c22:

replace remaining .html docs with .rst docs
Remove install.html (long since deprecated).
Also replace some obsolete references to install.html with references to quickstart.rst.
Fix some broken internal references within docs/historical/historical_known_issues.txt.
Thanks to Ravi Pinjala and Patrick McDonald?.
refs #1227