python - software - ¿Puede la esfinge enlazar a documentos que no están ubicados en directorios debajo del documento raíz?
sphinx software (5)
¡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
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
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:
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.
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(''..''))
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.