¿Puede Sphinx vincular a documentos que no se encuentran en directorios debajo del documento raíz?

Estoy usando Sphinx para documentar un proyecto que no es de Python. Quiero distribuir ./doccarpetas en cada submódulo, que contienen submodule_name.rstarchivos para documentar ese módulo. Luego quiero absorber esos archivos en la jerarquía maestra para crear una especificación para todo el diseño.

Es decir:

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

project_spec.rstIntenté incluir archivos en el documento maestro en un árbol como este:

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

Sin embargo, este mensaje de error resulta:

ADVERTENCIA: toctree contiene una referencia a un documento no existente u'modules / module1 / docs / module1 '

¿No es posible usarlo ../en una ruta de documento de alguna manera?

Actualización: agregada ubicación conf.py

Actualización: Aparte del truco de inclusión a continuación, esto todavía (2019) no es posible. Hay un problema abierto que sigue avanzando: https://github.com/sphinx-doc/sphinx/issues/701

¡Sí tu puedes!

En lugar de un enlace simbólico (que no funcionará en Windows), cree un documento auxiliar que no contenga nada más que una .. include::directiva.

Me encontré con esto tratando de vincular a un archivo README que estaba en la parte superior del árbol de fuentes. Pongo lo siguiente en un archivo llamado readme_link.rst:

.. include:: ../README

Luego index.rst, hice que el árbol pareciera:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Y ahora tengo un enlace a mis notas de lanzamiento en mi página de índice.

Gracias a http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html por la sugerencia

Parece que la respuesta es no, los documentos enumerados en el árbol toc deben residir dentro del directorio de origen , es decir, el directorio que contiene su documento maestro y conf.py(y cualquier subdirectorio).

De la lista de correo sphinx-dev :

En STScI, escribimos documentación para proyectos individuales en Sphinx, y luego también producimos un "documento maestro" que incluye (usando toctree) varios de estos otros documentos específicos del proyecto. Para hacer esto, creamos enlaces simbólicos en el directorio fuente de documentos del documento maestro a los directorios fuente de documentos de los proyectos, ya que toctree realmente no parece querer incluir archivos fuera del árbol de fuentes de documentos.

Entonces, en lugar de copiar archivos usando shutil, puede intentar agregar enlaces simbólicos a todos sus módulos en el Project/docs/specdirectorio. Si crea un enlace simbólico Project/modules, entonces hará referencia a estos archivos en su árbol toc simplemente como modules/module1/docs/module1etc.

En conf.py, agregue las rutas relativas al sistema usando sys.path y os.path

Por ejemplo:

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'))

Luego use su index.rst como de costumbre, haciendo referencia a los primeros archivos en el mismo directorio. Entonces en mi index.rst en mi carpeta local de Sphinx:

Contents:

.. toctree::
   :maxdepth: 4

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

Luego, en package1.rst, debería poder hacer referencia a los paquetes relativos normalmente.

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:

También es posible configurar sphinx para tener solo el archivo index.rst en la raíz y todas las demás cosas de sphinx en Project / docs:

Para Windows, moví todos los archivos y directorios de sphinx (excepto index.rst) a docs / y cambié:

docs/make.bat: Cambio

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

a

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

docs/conf.py: Agregar

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

Resolví mi problema bastante similar con la diferencia de que quería incluir un portátil jupyter externo. Había instalado nbsphinx pero no pude hacerlo funcionar. Lo que no funcionó:

1. Tenía el directorio que quería incluir la raíz en la ruta:

   conf.py:

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

2. El uso del .. include:: directivearchivo se incluyó en la documentación, pero tal como está.

Finalmente lo que resolvió el problema fue instalar el paquete nbsphinx-link

Una solución, si es realmente imposible usar enlaces relativos que respaldan ../es que podría usar shutilpara copiar los archivos en el árbol de carpetas de especificaciones en conf.pyla especificación, pero prefiero no tener varias copias a menos que sea absolutamente necesario.