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:
*
Related
(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 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?
In our read the docs project we have a use case where we need to show some specific docs on multiple pages in the same version of docs. As of now, we do this either by one of the following ways
Copy-pasting the content to each page's rst file
Write it in one of the concerned files with a label and use :std:ref: in rest of the files to redirect it to the main file
I would want to achieve something like writing content only in one file and then showing it (without any redirection for user) in each of the files. Is it possible?
Use the include directive in the parent file.
.. include:: includeme.rst
Note that the included file will be interpreted in the context of the parent file. Therefore section levels (headings) in the included file must be consistent with the parent file, and labels in the included file might generate duplicate warnings.
You can use for this purpose the include directive.
Say that you write the text in dir/text.rst.
The following will include in other documents:
..include :: /dir/text.rst
where the path is either relative (then, with no slash) or absolute which is possible in sphinx (doc)
in Sphinx, when given an absolute include file path, this directive
takes it as relative to the source directory
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.