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

Question 1

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

Question 2

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

Question

Answer