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
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 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.
I'm getting the warning:
WARNING: document isn't included in any toctree
for files that exist in the document because they've been explicitly included. So I have the index file:
.. toctree::
:maxdepth: 2
pages/0010-foo
pages/0020-bar
In the file 0020-bar.rst, I'm specifically including a number of other files, as in:
.. contents:: :local:
.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst
But when I build the project, I still get a warning that 0070-baz.rst isn't in any toctree, as in:
/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree
The weird thing is that I can see the content in the output. Is this normal? Does this warning always appear for files that are explicitly included rather than included via toctree?
If you only want to ..include:: a document in another document, without having it appear in any toctree.
Add :orphan: to the top of your document to get rid of the warning.
This is a File-wide metadata option. Read more from the Sphinx documentation.
Sphinx will complain about this whether the file is included or not.
However, you can specifically exclude files by using the exclude_patterns config value.
So for your case you might try to change Sphinx's conf.py file with something like:
exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']
You can exclude individual files, directories, or use file globbing patterns to match groups of files this way.
EDIT: See: Joakim's answer for another option that was added after this answer was created.
I had a situation where I couldn't edit the documents I wanted to be brought in as a git submodule. The documents already had their own structure including TOC page written in Markdown and I did want them to be processed by sphinx for consistency of formatting.
What I found I could do is specify a hidden toctree to make toctree aware of the documents, but not clutter up the toctree or add a bunch of errors to my sphinx build output.
* :doc:`Additional Book <external/index>`
.. toctree::
:hidden:
external/documentA.md
external/documentB.md
Indentation worked:
toctree::
:maxdepth: 2
hello <h.rst>
abc <your.rst>