I have modules I'd like to document such that the table of contents is on the main page index and the documentations themselves are in separate pages. I'm new to automatic documentation and Sphinx, but I've gotten close:
index.rst:
Documentation
*************
.. toctree::
:maxdepth: 2
Module1
Module2
Index
=====
* :ref:`genindex`
* :ref:`modindex`
Module1.rst and Module2.rst:
Title
*****
.. automodule:: Module1 (or Module2)
:noindex:
:members:
The reason for using noindex was getting duplicate object description errors. However this prevents the modules from showing up on the toctree of index. How might this be avoided? It seems like a basic thing one would do but I can't get my head around it.. Any help would be greatly appreciated!
It seems this question and its answer attempts to address a similar problem, but I don't think it's quite the same, as the OP commented on the answer.
Related
I am using Sphinx and ReStructuredText to create documentation, but even though all pages were created the same way, only 4 out of 8 are showing on the side menu. This is my table of contents:
.. toctree::
:glob:
:titlesonly:
*
I've tried to add the pages manually, but it didn't seem to work either.
Here's the link to the documentation where you can find the source code: Docs
You should use either correct syntax of the toctree directive when using its options, or use file names whose casing aligns with what you put in the toctree directive.
The .rst files in your directory are the following.
Coordenadas.rst
Galeria-mapa.rst
Home-page.rst
Lista-camadas.rst
index.rst
legenda.rst
marcador.rst
medicao.rst
oscilar.rst
But in your index.rst you use the incorrect case for those filenames, and you add a blank line between the file names and glob character without using the glob option.
.. toctree::
Home-page
Coordenadas
Galeria-mapa
Legenda
Lista-camadas
Marcador
Medicao
Oscilar
*
By looking at the build log on Read The Docs, you would find several warnings indicating what went wrong.
/home/docs/checkouts/readthedocs.org/user_builds/documentation-senografia/checkouts/latest/docs/source/index.rst:5: WARNING: toctree contains reference to nonexisting document 'Legenda'
To fix it, this is one option.
.. toctree::
Home-page
Coordenadas
Galeria-mapa
legenda
Lista-camadas
marcador
medicao
oscilar
And this should work, too. Note that in this version compared to yours, the options are immediately after the toctree directive without a blank line between them. A blank line should be present before the first toctree entry.
.. toctree::
:glob:
:titlesonly:
*
I'm currently writing a technical documentation with Sphinx.
I use a numbered toctree. When I insert an external web link in the toctree the rendered entry does not contain a number.
For this toctree :
.. toctree::
:numbered:
:hidden:
:maxdepth: 2
Administration <admin/admin.rst>
Usage <usage/usage.rst>
Squash TM - Squash TF Link <tm-tf-link/tm-tf.rst>
Download <https://squash-tf.readthedocs.io/en/latest/download.html#squash-tf-execution-server>
The "Download" entry has for result :
Does anyone has a tips for me ?
This seems to be a bug as #StevePiercy mentioned. I just submitted a bug report on it here. A similar issue is this one. However, you can set the missing index manually.
Hello world
============
.. toctree::
:numbered:
:hidden:
:maxdepth: 2
Administration <admin/admin.rst>
Usage <usage/usage.rst>
Squash TM - Squash TF Link <tm-tf-link/tm-tf.rst>
4. Download <https://squash-tf.readthedocs.io/en/latest/download.html#squash-tf-execution-server>
Output:
I am trying to generate a hierachical documentation in Sphinx.
I would like the following structure:
Introduction
Quick start
Weather API (one general page + 2 subpages)
Temperature
Humidity
Sky API (one general page + 3 subpages)
Planets
Stars
Satellites
Future API (one page is enough for this)
Assuming that there is one file per each line in the above TOC what should I do to achieve this?
I tried to include one or more .. toctree:: directives into the top index file, but the results seem to be quite random.
Create a directory and file structure that aligns with the following toctree entries, but the actual file names are appended with the .rst suffix.
.. toctree::
introduction
quick_start
weather_api/index
weather_api/temperature
weather_api/humidity
sky_api/index
sky_api/planets
sky_api/stars
sky_api/satellites
future_api/index
We do this in a part of Pyramid's documentation, although we also globbing because the order of the files is not important. Your order appears to have importance, so listing them in your desired order is necessary.
Currently I do this:
conf.py:
autosummary_generate = True
reference.rst:
package_1
---------
.. autosummary::
:toctree: _generated
package_1.module_1
package_1.module_2
package_1.module_3
...
This will generate an overview table for each module, with entries for each module
that nicely link to detail pages.
I have two questions:
Do I really have to enumerate every single module?
How can I control the options of the detail pages?
Ad 1.:
I would like to do s.th like this (which currently doesn't work):
.. autosummary:: package_1
:toctree: _generated
:members:
(Or maybe a new autopackage command.)
Ad 2.:
I would like to pass options like the ones that automodule or autoclass expect, e.g.:
.. autosummary::
:toctree: _generated
:undoc-members:
:private-members:
This seems to be an obvious task, so I am probably missing some information.
Is there an easy alternative way to accomplish this?
Thanks to all commenters!
Ad 1:
I list the modules manually.
Ad 2:
I finally went with the solution proposed by this and this answers to similar questions:
Create template files (_templates/autosummary/module.rst and _templates/autosummary/class.rst) and add this to
api_doc.rst:
Package ``wsgidav``
-------------------
.. autosummary::
:toctree: _autosummary
wsgidav._version
wsgidav.compat
I have the following page at plugins/index.html:
Plugin Development
==================
.. toctree::
:hidden:
basics/index
advanced/index
The Basics
----------
- :doc:`basics/gettingstarted`
- :doc:`basics/resources`
- :doc:`basics/i18n`
Advanced Topics
---------------
- :doc:`advanced/models`
- :doc:`advanced/controllers`
- :doc:`advanced/services`
plugin/basics/index.html and plugins/advanced/index.html contain their own toctree’s, which link to the same subpages listed in plugins/index.html. So what I’m wondering is, is there a way to just include those sub toctree’s, rather than manually listing the sub pages out like I’m doing?
I realize that I could just remove the :hidden: flag from the toctree, but the point is I want to keep Basic/Advanced topics in separate lists, with their own headings, intro paragraphs, etc.
You can list the entire directory contents like this (or various combinations of these directives):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
**
or I think also like this (untested):
.. toctree::
:glob:
:titlesonly:
:maxdepth: 2
*
basics/*
advanced/*
However, I have found just manually listing things is often the best way to go. While the automatically generated TOCs are nice, they don't allow you much room in terms of formatting (for example, creating sub headings, and changing the order of pages etc).
In our documentation I have done pretty much the same thing you did in the initial question.