¿Puede esfinge el enlace a documentos que no están ubicados en directorios debajo del documento raíz?

Question

Estoy usando Sphinx para documentar un proyecto que no es de Python. Quiero distribuir las carpetas ./doc en cada submódulo, que contiene submodule_name.rst archivos para documentar ese módulo. Luego quiero aspirar esos archivos a 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 

he tratado de incluir archivos en el maestro project_spec.rst documento toctree así:

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

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

Sin embargo, este error se produce mensaje:

ADVERTENCIA: toctree contiene referencia al documento no existente u'modules/module1/docs/module1 '

¿No es posible usar ../ en una ruta de documentos de alguna manera?

Actualización: Añadido ubicación conf.py

Answer 1

Sí, puede!

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

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

.. include:: ../README 

Luego, en index.rst, hice la toctree aspecto:

Contents: 

.. toctree:: 
    :maxdepth: 2 

    readme_link 
    other_stuff 

Y ahora tengo un enlace a mis notas de la versión en mi página de índice.

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

Answer 2

Una solución, si es realmente imposible de usar enlaces relativos que respaldan ../ es que podría utilizar shutil para copiar los archivos en el árbol de carpetas de especificaciones en el conf.py para el especificaciones, pero prefiero no tener múltiples copias a menos que sea absolutamente necesario.

Answer 3

Parece que la respuesta es no, los documentos que se indican en el toc-árbol debe residir dentro del source directory, es decir, el directorio que contiene sus master document y conf.py (y los subdirectorios).

Desde el sphinx-dev mailing list:

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

Así que en lugar de copiar archivos mediante shutil que podrían intentar añadir enlaces simbólicos a todos sus módulos en el directorio Project/docs/spec. Si crea un enlace simbólico al Project/modules, entonces haría referencia a estos archivos en su toc-tree simplemente como modules/module1/docs/module1 etc.

Answer 4

También es posible configurar la esfinge de tener sólo el archivo index.rst en la raíz y el todas las otras cosas Esfinge en Proyecto/docs:

para ventanas me moví todos los archivos y directorios esfinge (excepto index.rst) en docs/y ha cambiado:

docs/make.bat: Cambio

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

a

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

docs/conf.py: Añadir

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

Answer 5

En conf.py, añadir las rutas relativas al sistema utilizando 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. Así que en mi index.rst en mi carpeta local Sphinx:

Contents: 

.. toctree:: 
    :maxdepth: 4 

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

Luego, en package1.rst, usted debería ser capaz de simplemente 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: