generate docs with sphinx

[zooko]

Sphinx apparently makes docs have nice formatting which looks like software docs style. It also provides cross-referencing (e.g. a table of contents).

Here is an example:

​https://zooko.com/uri/URI%3ADIR2-MDMF-RO%3Afz45kpgz2hhjb7t2xhoscntdqi%3A2lcyvnawrwn7mhnlps5rbw52kybaurrsocktpz7b3s367xrusrnq/index.html

Here is a pull request:

​https://github.com/tahoe-lafs/tahoe-lafs/pull/70

[zooko]

I looked at ​https://zooko.com/uri/URI%3ADIR2-MDMF-RO%3Afz45kpgz2hhjb7t2xhoscntdqi%3A2lcyvnawrwn7mhnlps5rbw52kybaurrsocktpz7b3s367xrusrnq/index.html . It looks nice! But it has broken links, such as the link on ​What Is Provider-Independent Security? with anchor text "quickstart.rst", which points to ​./quickstart.rst.

[daira]

It looks like links with filetype .rst should be rewritten to .html. This can probably be done on the source with a sed replacement before running it thorough sphinx.

[daira]

Besides that, I really like these docs. They make all the doc files much more discoverable and navigable.

[zooko]

Here is an unanswered Stack Overflow question about how to do this: ​http://stackoverflow.com/questions/16977926/sphinx-restructuredtext-to-html-hyperlink-conversion

[Novacha]

What you will want to use is the :doc: directive (At ​http://sphinx-doc.org/markup/inline.html#role-doc). You will want to replace the following

To use Tahoe-LAFS, please see quickstart.rst_.

With

To use Tahoe-LAFS, please see :doc:`quickstart`

You can also name the link what you want

To use Tahoe-LAFS, please see :doc:`the quickstart guide <quickstart>`

Though you can do this, the files you reference MUST be included in a toctree so that sphinx knows the hierarch of the file. It is not good enough just to reference it like this (and the sphinx builder will throw errors if this is the case). You can create a hidden toctree on the front page to include all these files.

The syntax in the line below is something that I have not seen before, and I do not believe it is a valid way of using labels.

 .. _quickstart.rst: quickstart.rst

The solution above with the :doc: directive is the way to go with all the links that are formatted this way. You could also place labels at the top of sections and files (such as putting .. _quickstart: at the top of the quickstart.rst file and referencing it like :ref:`quickstart`). The documentation for this method can be found at ​http://sphinx-doc.org/markup/inline.html#role-ref

[zooko]

Assigning to ambimorph. ambimorph: are you willing to try to fix the problem described in comment:1, probably using the technique suggested by Novacha in comment:5?

[exarkun]

Pull request was merged some great while ago.