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

One solution, if it’s really impossible to use relative links that back up ../ is that I could use shutil to copy the files into the spec folder tree in the conf.py for the spec, but I’d rather not have multiple copies unless absolutely necessary.

It seems that the answer is no, the documents listed in the toc-tree must reside within the source directory, that is, the directory containing your master document and conf.py (and any subdirectories).

From the sphinx-dev mailing list:

At STScI, we write documentation for individual projects in Sphinx, and then also produce a “master document” that includes (using toctree) a number of these other project-specific documents. To do this, we create symlinks in the master document’s doc source directory to the projects’ doc source directories, since toctree really doesn’t seem to want to include files outside of the doc source tree.

So rather than copying files using shutil you could try adding symlinks to all of your modules in the Project/docs/spec directory. If you create a symlink to Project/modules you would then reference these files in your toc-tree simply as modules/module1/docs/module1 etc.

It is also possible to configure sphinx to have only the index.rst file in the root and the all the other sphinx stuff in Project/docs:

For windows I moved all sphinx files and dirs (except index.rst) into 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('..'))

In conf.py, add the relative paths to system 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 rst files in the same directory. So in my index.rst in my local Sphinx folder:

Contents:

.. toctree::
   :maxdepth: 4

   Package1 <package1.rst>
   Package2 <package2.rst>
   Package3 <package3.rst>

Then in package1.rst, you should be able to just reference the relative packages normally.

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:

I solved my quite similar problem with the difference I wanted to include an external jupyter notebook. I had installed nbsphinx but I couldn’t get it to work.
What did not work:

1. I had the directory I wanted to include the root in the path:

   conf.py :

   import os
import sys
sys.path.insert(...

2. Using the .. include:: directive the file was included in the documentation but as is.

Finally what solved the problem was installing package nbsphinx-link

An alternate technique which does not require the creation of stub files is to use absolute references (starting with /) within your toctree root, and setting the source directory to the lowest common ancestor when calling sphinx-build. Example directory layout:

/path/to/common/ancestor
├── a
│   └── foo.rst
├── b
│   ├── bar.rst
│   ├── x
│   │   └── index.rst
│   └── y
│       └── boz.rst
└── c
    └── baz.rst

And b/x/index.rst:

.. toctree::
   /a/foo
   /b/bar
   /b/y/boz
   /c/baz

And your sphinx-build command might look like this:

sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>

I tested this with sphinx 3.0.2.

My answer is in essence the @Dan Menes, but for Myst parser instead of reStructured.

I would prefer to add this as a comment to @Dan Menes answer as it belongs there, but comments do not allow me to do the formatting, the Myst syntax is sensitive to newlines and the comments are limited in characters. So I’m posting it as a separate answer, even when it’s related to an existing answer.

To do include in the Myst you have to format it slightly differently:

```{include} ../main/post_installation_windows.md
```

It can wrap itself to do the reStructured markup too (which then included file will be treated as it’s written in restructured):

```{eval-rst}
.. include:: snippets/include-rst.rst
```

However, using the native Myst syntax is easier. And it has better features, for example, just including the file will not resolve correctly any references inside the included file, while include-literal should:

```{include-literal} ../../example.md
:language: md
```

As you might discover that including a simple document is ok, but then including a complex document with many references will cause more headaches, so I would recommend the experimental include-literal (from version 0.12.7)

Reference:
https://myst-parser.readthedocs.io/en/latest/using/howto.html