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.
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.
How can I get my Sphinx RST file to include a link to the "contents.html" Python help page?
More Details
I have an RST help document (index.rst) in an offline environment. I have downloaded and successfully built the Python documentation using the command make.bat html. I then copied this documentation to C:\Temp\PyDoc.
I then updated my conf.py file to include the following Intersphinx mapping:
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
Then, within my index.rst file, I have something like:
Contents:
.. toctree::
:maxdepth: 1
:ref:`Python <python:contents>`
The Python link is removed from the resulting documentation with the warning message:
WARNING: toctree contains reference to nonexisting document ':ref:`Python <python:contents>`'
I have verified that the output contains the text:
loading intersphinx inventory from C:/Temp/PyDoc/objects.inv...
I have also verified that the "contents" tag exists within the Python documentation by running:
python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents
Which generates output that includes the line:
contents Python Documentation contents : contents.html
Does anyone know how to reference this external documentation from my RST file?
In the configuration for intersphinx, the dict's key's value is a tuple, which consists of comma-separated values, not colon-separated.
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
EDIT
toctree entries need a valid target, which can be a file relative to the current file or absolute as starting from the documentation root where your conf.py resides. Also the target may be an URL. I suspect that the HTML you made is none of the above, so you need to move it to a place where Sphinx can find it.
The syntax should be for documentation, not a Python object, because the page is a table of contents. I did not try this example because I don't have the Python docs downloaded and built, so I doubt it will work.
.. toctree::
:maxdepth: 1
:doc:`Python <python:contents>`
Or you can just use the URL (or similar relative or absolute target). This works for me with a fully qualified URL.
.. toctree::
:maxdepth: 1
Python <https://docs.python.org/3/contents.html>
Finally you could try an include, but I think that is not what you really want.
I wish to create an single_html.rst file that contains all my class/method/attribute/etc... , but also split categorised symbols into seperate pages.
e.g.
single_html.rst
.. single html
.. include:: foo.rst
.. include:: bar.rst
bar.rst
.. autoclass:: my.mod.Bar
:members:
foo.rst
.. autoclass:: my.mod.Foo
:members:
This throws multiple duplicate object description errors:
/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Bar, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them
/path/to/project/my/mod.py:docstring of my.module.Bar:0: WARNING: duplicate object description of my.mod.Foo, other instance in /path/to/project/docs/source/api/single_html.rst, use :noindex: for one of them
I can't simply place :noindex: on the autoclass:: directives as this will remove all the indexes completely. (so there are either duplicate indexes or none at all!)
Is there a better way to do this?
You can avoid those warnings by changing the extension of included files.
Sphinx considers each .rst (by default, it can be changed in the conf.py file) as a "source to parse" file. So it will try to parse the foo.rst and the bar.rst files and find autodoc directives for my.mod.Foo and my.mod.Bar.
When it tried to parse single_html.rst, it first include the content of foo.rst and bar.rst; thus, it then find again the directives for my.mod.Foo and my.mod.Bar.
By renaming foo.rst and bar.rst to foo.inc and bar.inc (of whatever you want as extension), you will prevent Sphinx from parsing the included files and will avoid the warnings.
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'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>