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:
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 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 using sphinx and I created multiple rst files to organize my documents. I used .. include:: <filepath/filename.rst> to include multiple rst files into one config file but when using :ref:`<reference>` this maintains the file name header label but when I click the link it isolates the page but I want it to scroll to the reference in the same page. When I use <reference>_ this will scroll to the area within the same document but no longer keeps the header label. Is there a way I can keep the reference header label and scroll within the same page while still keeping the the docs in different files?
index.rst
Welcome to testing's documentation!
===================================
.. toctree::
:maxdepth: 2
:caption: Contents:
test/config
test/config.rst
.. title:
Hello moto
==========
Using ref maintains header
* :ref:`ref-nested`
Using underscore doesn't maintain header
- nested_
.. include:: nested_test/file.rst
.. include:: nested_test/anotherfile.rst
test/anotherdir/file.rst
.. _nested:
I'm a nested header
-------------------
Hi I'm the created nested header
test/anotherdir/anotherfile.rst
.. _ref-nested:
I'm the ref nested header
-------------------------
I'm the ref nested header
As you see below the first link(:ref:) maintains the header given but if you click it, it will go to an isolate page. The second link doesn't maintain the header give but uses the actual reference but if clicked it will stay on the same page and would move within the document.
Below are two images, when using :ref: it loads the page as an isolated rst file.
I want the link to scroll down as if within the document.
If I understand what you want, you can move the target and its header from the included file into the main file.
.. title:
Hello moto
==========
Using ref maintains header
* :ref:`ref-nested`
Using underscore doesn't maintain header
- nested_
.. _nested:
I'm a nested header
-------------------
.. include:: nested_test/file.rst
.. _ref-nested:
I'm the ref nested header
-------------------------
.. include:: nested_test/anotherfile.rst
This has an added benefit that if you include your included files in more than one file, then you can specify a unique target and avoid Sphinx errors.
I found the answer I wanted on a different stack overflow question here. I don't have to create a reference if it's in the same file using include I can reference the title itself. Refer to the link and see #Baleb answer.
How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?
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 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.