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.
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:
*
(Note: this is similar to Conditional output in Sphinx Documentation, but it's not clear if the solution there is usable.)
I have some documentation of two functions that are very similar. What I want to write is a file that would be included by the doc for both that looks like:
.. if:: doc_for_foo
This documentation only applies to ``foo``.
.. if:: doc_for_bar
This documentation only applies to ``bar``.
This documentation applies to both.
So, the common content would appear in two separate pages of the same generated documentation. Is there a way to do this? (I know about .. only, but it isn't clear how I would enable the relevant bits for each documentation page.)
Note: I don't want to just split the common stuff into separate files, because the content is significantly interleaved. That is, I would end up with:
Text about ``foo``.
.. include:: common-part-1
More text.
.. include:: common-part-2
.. for 'foo', no intervening text here
.. include:: common-part-3
More text.
.. include:: common-part-4
...and so on, where each part is perhaps a single paragraph. IOW, the former would be much easier to maintain.
To clarify, I want something like:
.. foo.rst
.. enable-tag:: doc_for_foo
.. include:: foo_and_bar_doc
.. bar.rst
.. enable-tag:: doc_for_bar
.. include:: foo_and_bar_doc
...where both foo.rst and bar.rst are generated by the same run of Sphinx. Passing -t at build time won't work; both foo.rst and bar.rst would (AFAIU) see the same set of tags set. Same with anything I did in conf.py.
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 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.