python - software - ¿Puede la esfinge enlazar a documentos que no están ubicados en directorios debajo del documento raíz?

sphinx software

Question

Estoy usando Sphinx para documentar un proyecto que no es Python. Quiero distribuir ./doc carpetas ./doc en cada submódulo, que contiene los archivos submodule_name.rst 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.rst incluir archivos en el documento maestro project_spec.rst trabajar como este:

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

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

Sin embargo, este mensaje de error resulta:

ADVERTENCIA: toctree contiene referencias a documentos no existentes u''modules / module1 / docs / module1 ''

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

Actualización: Se agregó la ubicación conf.py

Answer 1

¡Sí tu puedes!

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

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

.. include:: ../README

Luego, en index.rst , hice que el toctree pareciera:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Y ahora tengo un enlace a mis notas de publicació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

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. Así que 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 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:

Answer 3

Parece que la respuesta es no, los documentos enumerados en el árbol de caracteres 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 de sphinx-dev :

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

Entonces, en lugar de copiar archivos usando shutil , puede intentar agregar enlaces simbólicos a todos sus módulos en el directorio Project/docs/spec . Si creas un enlace simbólico a Project/modules , entonces harías referencia a estos archivos en tu árbol de caracteres simplemente como modules/module1/docs/module1 etc.

Answer 4

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

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

docs/make.bat : Cambiar

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

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