Can sphinx link to documents that are not located in directories below the root document?

python, python-sphinx, symlink, toctree

Solution

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

Problem

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

Original source

Related problems