generate docs with sphinx #2102

New Issue

zooko · 2013-11-12T16:12:38Z

zooko commented

2013-11-12 16:12:38 +00:00

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

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 added the

labels 2013-11-12 16:12:38 +00:00

zooko added this to the soon (release n/a) milestone 2013-11-12 16:12:38 +00:00

zooko commented

2013-11-12 16:26:31 +00:00

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.

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?](https://zooko.com/uri/URI%3ADIR2-MDMF-RO%3Afz45kpgz2hhjb7t2xhoscntdqi%3A2lcyvnawrwn7mhnlps5rbw52kybaurrsocktpz7b3s367xrusrnq/index.html) with anchor text "quickstart.rst", which points to [./quickstart.rst](https://zooko.com/uri/URI%3ADIR2-MDMF-RO%3Afz45kpgz2hhjb7t2xhoscntdqi%3A2lcyvnawrwn7mhnlps5rbw52kybaurrsocktpz7b3s367xrusrnq/quickstart.rst).

daira commented

2013-11-17 21:12:30 +00:00

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.

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 commented

2013-11-17 21:19:36 +00:00

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

zooko commented

2013-11-21 22:56:42 +00:00

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

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

Novacha commented

2013-11-29 22:42:42 +00:00

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

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 commented

2014-06-09 18:30:19 +00:00

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

Assigning to ambimorph. ambimorph: are you willing to try to fix the problem described in [comment:93851](/tahoe-lafs/trac-2024-07-25/issues/2102#issuecomment-93851), probably using the technique suggested by Novacha in [comment:93855](/tahoe-lafs/trac-2024-07-25/issues/2102#issuecomment-93855)?

exarkun commented

2020-01-20 20:31:48 +00:00

Pull request was merged some great while ago.

exarkun added the

fixed

label 2020-01-20 20:31:48 +00:00

exarkun closed this issue

2020-01-20 20:31:48 +00:00

Sign in to join this conversation.