I have rst document like:
######
Title
######
.. toctree::
:hidden:
:titlesonly:
subpage1
subpage2
subpage3
Section1
---------
Section2
---------
This results in toctree
Title
subpage1 title
subpage2 title
subpage3 title
Section1
Section2
Is there a way to remove the Section1 and Section2 from the toctree - I want in it, only what I explicitly stated
It seems adding :titlesonly: to the parent document toctree directive achieved what I wanted.
Related
I have a Sphinx project that has the following structure:
projectRoot
|
|__mainDoc
| |__conf.py
| |__index.rst
|
|__subsections
|__subsectionA.rst
|__subsectionB.rst
In my conf.py, I have set my master_doc variable to "mainDoc/index", and to build the project I run the following command at the projectRoot directory: sphinx-build -c ./mainDoc -b singlehtml . _build
index.rst contains a simple toctree directive that lists the two subsection files like so:
.. toctree::
:numbered:
:hidden:
:maxdepth: 4
:caption: Contents:
../subsections/subsectionA
../subsections/subsectionB
subsectionA.rst:
.. _anchorA:
First Title
===========
This is a sample sentence.
subsectionB.rst:
Second Title
============
Please refer to :ref:`this sentence <anchorA>`
So far everything is pretty straightforward, and I was able to successfully build an HTML file. However, the cross-references are broken. Specifically, if the generated HTML file is in _build/maindoc/index.html, the link in subsectionB.rst points to _build/maindoc/maindoc/index.html#anchora, which is a file that doesn't exist since there's an extra maindoc folder in the path.
What is causing that extra folder to be inserted in the link target, and what can I do to fix that? Thanks in advance.
This is my project structure:
base/devices.py
users/devices.py
company/devices.py
Here is my index.rst:
.. My documentation master file.
Welcome to documentation!
=========================
.. toctree::
:maxdepth: 3
:caption: Contents:
users.rst
company.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
base/devices.txt:
.. automodule:: base.devices
:noindex: # base docs may be included in several .rst files
:members:
users.rst and company.rst are similar:
USERS
*****
Devices
=======
.. include:: base/devices.txt
.. automodule:: users.devices # in company.rst "company.devices"
:members:
In base/devices.py I have a function check_devices()
In users/devices.py I have function check_devices() but with another docstring and another behaviour
And when I generate documentation in my users page I can see both functions: base.devices.check_devices and users.devices.check_devices
How can I exclude base.devices.check_devices docstring from users page without losing possibility to include base/devices.txt in several rst files and without copy-paste style?
The structure of my project that I want to document is as follows:
/top
Index.rst
/a
toctree_a.rst (contains doc and doc2)
doc.rst
doc2.rst
/b
toctree_b.rst (contains doc4 and doc3)
doc3.rst
doc4.rst
I want to reference the toctrees in the sub-directories (a and b) so that the project toctree can see the 4 documents in the project tree.
I know how do do this when the documents are in one directory, but I don't know how to do this if I have them in a subdirectory. I am trying to keep the structure of my project intact without having to move all files into one directory. I have done some research, and found that .. include:: directive may be the route to go, but I could not figure out how to use it properly.
you can tell your toctree in your index.rst to get the file from a sub-directory like so:
Contents:
.. toctree::
:maxdepth: 2
a/doc
a/doc2
b/doc3
b/doc4
That method works just like they would be in the same directory
I have a very basic setup in Sphinx. The TOC is as follows:
.. toctree::
:maxdepth: 3
one
two
And the files one and two look like this:
one.rst
####
Part
####
*******
Chapter
*******
Section
=======
two.rst:
***************
Another Chapter
***************
Another Section
===============
Both files have the same formatting and I would like to end up with the following structure
Part
|- Chapter
|- Section
|- Another Chapter
|- Another Section
However, Sphinx gives me
Part
|- Chapter
|- Section
Another Chapter
|- Another Section
The reason I'm splitting the files is that they are fairly large and I want to keep them small so I can edit them easily. How can I get the same heading styles (with the same overline/underline characters) but in different files?
I believe what you want is the include directive. For example in 1.rst you will put
####
Part
####
*******
Chapter
*******
Section
=======
.. include:: 2.rst
.. include:: 3.rst
.. include:: 4.rst
This will include 2.rst and however many additional files you want in the current file and continue the current structure layout. Also, change your index.rst to be just the 1.rst.
.. toctree::
:maxdepth: 3
1.rst
part2.rst
part3.rst
I have just created my documentation using Sphinx and this is my problem:
Initially in the Toc tree directive is empty and then I add "tutorial" below and it looks like this:
.. toctree::
:maxdepth: 2
tutorial
and when I "make html", I do not get "tutorial" on the index page. Then I created a tutorial.rst in the same dircetory as index.rst. I do "make html"again and I get this error message:
toctree contains reference to nonexisting document
How do I fix this ?
Maybe try this :
.. toctree::
:maxdepth: 2
tutorial <tutorial>
..
Assuming your tutorial.rst file is in the "source" directory at the same level of your index.rst file
NOTE: newline is important between toctree options and page list.
You have to have an empty line between the maxdepth definition and the filename.