I am using Sphinx to document a non-Python project. I want to distribute
./doc folders in each submodule, containing
submodule_name.rst files to document that module. I then want to suck those files into the master hierarchy to create a spec for the entire design.
Project docs spec project_spec.rst conf.py modules module1 docs module1.rst src module2 docs module2.rst src
I attempted to include files in the master
project_spec.rst document toctree like this:
.. toctree:: :numbered: :maxdepth: 2 Module 1 <../../modules/module1/docs/module1>
However this error message results:
WARNING: toctree contains reference to nonexisting document u’modules/module1/docs/module1′
Is it not possible to use
../ in a document path somehow?
Update: Added conf.py location
Other than the include trick below, this is still (2019) not possible. There is an open issue that keeps getting pushed forward: https://github.com/sphinx-doc/sphinx/issues/701
Yes, you can!
In lieu of a symlink (which won’t work on Windows), create a stub document that has nothing in it but a
.. include:: directive.
I ran into this trying to link to a README file that was in the top of the source tree. I put the following in a file called
.. include:: ../README
index.rst, I made the toctree look like:
Contents: .. toctree:: :maxdepth: 2 readme_link other_stuff
And now I have a link to my release notes on my index page.
Thanks to http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html for the suggestion
It seems that the answer is no, the documents listed in the toc-tree must reside within the source directory, that is, the directory containing your master document and
conf.py (and any subdirectories).
From the sphinx-dev mailing list:
At STScI, we write documentation for individual projects in Sphinx, and then also produce a “master document” that includes (using toctree) a number of these other project-specific documents. To do this, we create symlinks in the master document’s doc source directory to the projects’ doc source directories, since toctree really doesn’t seem to want to include files outside of the doc source tree.
So rather than copying files using
shutil you could try adding symlinks to all of your modules in the
Project/docs/spec directory. If you create a symlink to
Project/modules you would then reference these files in your toc-tree simply as
In conf.py, add the relative paths to system using sys.path and os.path
import os import sys sys.path.insert(0, os.path.abspath('..')) sys.path.insert(0, os.path.abspath('../../Directory1')) sys.path.insert(0, os.path.abspath('../../Directory2'))
Then use your index.rst as usual, referencing the rst files in the same directory. So in my index.rst in my local Sphinx folder:
Contents: .. toctree:: :maxdepth: 4 Package1 <package1.rst> Package2 <package2.rst> Package3 <package3.rst>
Then in package1.rst, you should be able to just reference the relative packages normally.
Package1 package ===================== Submodules ---------- Submodule1 module ---------------------------------- .. automodule:: file_within_directory_1 :members: :undoc-members: :show-inheritance: Submodule1 module ---------------------------------- .. automodule:: file_within_directory_2 :members: :undoc-members: :show-inheritance:
It is also possible to configure sphinx to have only the index.rst file in the root and the all the other sphinx stuff in Project/docs:
For windows I moved all sphinx files and dirs (except index.rst) into docs/ and changed:
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% -c . ..
I solved my quite similar problem with the difference I wanted to include an external jupyter notebook. I had installed nbsphinx but I couldn’t get it to work.
What did not work:
I had the directory I wanted to include the root in the path:
.. include:: directivethe file was included in the documentation but as is.
Finally what solved the problem was installing package nbsphinx-link
One solution, if it’s really impossible to use relative links that back up
../ is that I could use
shutil to copy the files into the spec folder tree in the
conf.py for the spec, but I’d rather not have multiple copies unless absolutely necessary.