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

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

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.

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: