Asked By – mc_electron
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
Now we will see solution for issue: Can sphinx link to documents that are not located in directories below the root document?
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