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

Question

I use Sphinx to document a non-Python project. I want to distribute ./doc folders in each submodule containing submodule_name.rst files to document this module. Then I want to add these files to the main hierarchy in order to create a specification for the entire project.

those.:

 Project docs spec project_spec.rst conf.py modules module1 docs module1.rst src module2 docs module2.rst src 

I tried to include the files in the main project_spec.rst document, for example like this:

 .. toctree:: :numbered: :maxdepth: 2 Module 1 <../../modules/module1/docs/module1> 

However, this error message results in:

ATTENTION: toctree contains a link to a non-existent document u'modules / module1 / docs / module1 '

Isn't it possible to use ../ in a document path?

Update: conf.py location added

Update: Apart from the inclusion trick below, it is still (2019) impossible. There is an open issue that keeps coming up: https://github.com/sphinx-doc/sphinx/issues/701

Answer 1

Yes, you can!

Instead of a symbolic link (which will not work on Windows), create a stub document in which there is nothing but the .. include:: directive.

I came across this while trying to link it to a README file, which was located at the top of the source tree. I put the following in a file called readme_link.rst :

 .. include:: ../README 

Then in index.rst I did this:

 Contents: .. toctree:: :maxdepth: 2 readme_link other_stuff 

And now I have a link to my release notes on my index page.

Thanks http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html for the suggestion

Answer 2

It seems that the answer is no, the documents listed in the toc-tree should be in the source directory , that is, in the directory containing the main document and conf.py (and any subdirectories).

From the sphinx-dev mailing list :

In STScI, we write documentation for individual projects in Sphinx, and then also create a “main document” that includes (using toctree) a number of other documents related to specific projects. To do this, we create symbolic links in the source directory of the doc source document in the project source directories, since toctree really does not want to include files outside the source tree.

Therefore, instead of copying files using shutil you can try adding symbolic links to all your modules in the Project/docs/spec directory. If you create a symbolic link to Project/modules , you will refer to these files in your toc tree just like modules/module1/docs/module1 , etc.

Answer 3

In conf.py add relative system paths using sys.path and os.path

For example:

 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 first files in the same directory. Therefore, in my index.rst in my local Sphinx folder:

 Contents: .. toctree:: :maxdepth: 4 Package1 <package1.rst> Package2 <package2.rst> Package3 <package3.rst> 

Then in package 1.rst you should be able to just refer to relative packages as usual.

 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: 

Answer 4

One solution, if it is really impossible to use relative links that support ../ , is that I could use shutil to copy files to the spec tree in conf.py for the specification, but I would most likely not have several copies if absolutely necessary.

Answer 5

You can also configure sphinx to have only the index.rst file in the root directory and all other sphinxes in Project / docs:

For windows, I moved all sphinx and dirs files (except index.rst) to docs / and changed:

docs/make.bat : Change

 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . 

to

 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% -c . .. 

docs/conf.py : Add

 sys.path.insert(0, os.path.abspath('..'))