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.
I.e.:
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
Update: 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 readme_link.rst
:
.. include:: ../README
Then in 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