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


90

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


¿Necesita agregar la .rstextensión a la línea Module 1 <../../modules/module1/docs/module1>?
Chris

No lo creo porque en Sphinx Docs : dado que los archivos fuente reST pueden tener diferentes extensiones (a algunas personas les gusta .txt, a otras les gusta .rst, la extensión se puede configurar con source_suffix) y los diferentes sistemas operativos tienen diferentes separadores de ruta, Sphinx los abstrae: todos los "nombres de documentos" son relativos al directorio de origen, la extensión se elimina y los separadores de ruta se convierten en barras.
mc_electron

¡Bien, solo una suposición! Así que supongo que source_suffixestá configurado .rsten su conf.pyarchivo de configuración. Además, ¿dónde está este archivo en la jerarquía de su directorio, ya que parece que todas las rutas son relativas a este archivo?
Chris

Sí, source_suffixestá configurado en .rsty conf.pyestá en la misma carpeta que el project_spec.rstarchivo.
mc_electron

Respuestas:


108

¡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


5
Si el archivo README tiene imágenes o similares que tienen rutas relativas que no son válidas dentro del directorio index.rst, ¿cómo lo maneja? Recibo errores de "archivo de imagen no legible".
Lucas W

Sí, también puede hacerlo en Unix con enlaces simbólicos. Puede crear un enlace con el mismo nombre que la carpeta de documentos (es decir docs) que enlaza con el directorio actual ('.'). Luego puede usar: download: docs\foo.rsty esto funcionaría para archivos dentro de la docscarpeta o su padre.
ankostis

1
Acabo de volver aquí y acepté esta respuesta, ¡gracias! No estoy seguro de las imágenes, pero siempre puede copiarlas en conf.py.
mc_electron

11
Necesitaba usar .. include:: ../readme.rstincluida la extensión.
nu everest

1
Para incluir solo una parte del archivo README.rst: muffinresearch.co.uk/…
ederag

14

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.


3
Eso es muy malo. Una de las ventajas que veo al intentar cambiar de documentos de Word a Sphinx es que puede importar un módulo de hardware reutilizable en su proyecto y simplemente incluir su documentación en la documentación maestra para el diseño. Usaría enlaces simbólicos pero, por desgracia, estoy en Windows.
mc_electron

Para la posteridad, intenté agregar la carpeta doc del submódulo sys.pathen conf.py, pero no funcionó.
mc_electron

1
@mc_electron Para enlaces simbólicos en Windows, use el comando mklink.
Jeremy

11

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:

¿Es este nuevo comportamiento? ¿En qué versión se agregó?
mc_electron

2
Sería genial si se describe más detalladamente para informar a los principiantes. Por ejemplo, ¿qué es Package1? ¿Es ese el primer pathuso especificado sys.path.insert? ¿O hay un tutorial en alguna parte? Parece que no puedo encontrar el documento relevante.
Manavalan Gajapathy

Package1es una entrada con nombre para que la tabla de contenido muestre "Paquete1" como título de la sección.
PabloC

2
Esto le permite autodoc de módulos Python en otro directorio, pero no le permite incluir archivos RST en otro directorio.
mc_electron

1

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

¡Gracias! Esa configuración funciona bien para mí cuando tengo varios paquetes relacionados en un repositorio, referenciados en la misma documentación.
Gregor Müllegger

1

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


0

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.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.