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

Michael Zippo

👻 Check our latest review to choose the best laptop for Machine Learning engineers and Deep learning tasks!

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

👻 Read also: what is the best laptop for engineering students?

We hope this article has helped you to resolve the problem. Apart from Can sphinx link to documents that are not located in directories below the root document?, check other ast Python module-related topics.

Want to excel in Python? See our review of the best Python online courses 2023. If you are interested in Data Science, check also how to learn programming in R.

By the way, this material is also available in other languages:

Chen Galleotti

New York | 2023-03-22

Thanks for explaining! I was stuck with Can sphinx link to documents that are not located in directories below the root document? for some hours, finally got it done 🤗. I am just not quite sure it is the best method

Jan Krasiko

Texas | 2023-03-22

I was preparing for my coding interview, thanks for clarifying this - Can sphinx link to documents that are not located in directories below the root document? in Python is not the simplest one. Checked yesterday, it works!

Marie Gonzalez

Milan | 2023-03-22