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.
Related
I am new to Sphinx and I don't seem to find the way to achieve this. I want to be able to quickly comment/uncomment single toctree entries as I progress, without having to remove the line. I use to do this in Latex to reduce the compilation time while my project is still in progress.
For instance, I'd like to achieve something like this:
.. toctree::
file1
file2
.. file3 (I want to comment/uncomment this, easily)
file4
.. file5 (this also fails)
..
file6 (this also fails)
What is the right way to do it?
Have you tried using the :hidden: option under the toctree directive?
I image you'd need to have two separate toctree directives to achieve this though:
.. toctree::
visiblefile1
visiblefile2
.. toctree::
:hidden:
hiddenfile1
hiddenfile2
See also sphinx-doc.org.
Perhaps this achieves acceptable results. Its not exactly commenting/uncommenting, but it achieves the same result.
It seems I might have found something close to a solution (the closest so far). It consists of putting the .. unindented, that is, at the same level as the toctree directive. For instance, I get something like this:
.. toctree::
Title 1 <file1>
Title 2 <file2>
Title 4 <file4>
.. the comment starts here
Title 3 <file3>
Title 5 <file5>
etc
And having this, the best approach to 'comment/uncomment' I can get is by selecting the target line and drag&droping it into the commented/uncommented area, respectively.
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.
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.
I've learnt that it's possible to maintain my documentation in a modular form with parts/chapters etc. across multiple files by using the include command.
The only problem with this approach is that it effectively concatenates all included files into one big file, which means that they are no longer treated as separate pages by the Sphinx Read The Docs theme.
As a consequence of this, the documentation has very long pages that users have to scroll down, rather than short pages with previous/next buttons for navigation. I would like my documentation to have the latter structure because I think that it creates a much more comfortable user experience.
How can I preserve part/chapter structure without creating a single, long, page?
Basing myself on the earlier question that you reference, I should warn you about the solution that is given there or more so about the question itself :-)
Your document did not reproduce the headings properly ("part" against "chapter") because the toctree directive considers the first heading in the included document as the "top heading" of that document. The other solution was to move the
######
Part 1
######
part in the main file, the one with the toctree directive.
######
Part 1
######
.. toctree::
:maxdepth: 2
test1
test2
I learned about this through experience. I cannot find a proper reference about this, though.