python - links - sphinx tutorial español

Combinando la documentación de Sphinx de múltiples subproyectos: manejo de índices, configuración de sincronización, etc.

Question

Tenemos un proyecto de varios módulos documentado con la (excelente) Sphinx. Nuestra configuración no es diferente a la descrita en la lista de correo . En general, esto funciona muy bien ! Pero tenemos algunas preguntas acerca de hacerlo:

1. Las tablas de contenidos del submódulo incluirán enlaces de índice. En el mejor de los casos, estos se vincularán a los índices incorrectos. (En el peor de los casos, esto parece provocar un error en Sphinx, pero estoy usando la versión devel, así que es razonable). ¿Hay una manera de generar los enlaces de índice solo para el toctree superior?

2. ¿Existen prácticas recomendadas para mantener la configuración de Sphinx sincronizada entre varios proyectos? Podía imaginarme hackear algo juntos from common_config import * , pero con curiosidad sobre otros enfoques.

3. Mientras estamos en eso, la pregunta planteada en la publicación de la lista de correo (¿alternativa a la simulación de documentos de subproyectos?) Nunca fue respondida. No es importante para mí, pero puede ser importante para otros lectores.

Answer 1

1. No estoy seguro de lo que quieres decir con esto. El index su proyecto parece estar bien. ¿Podrías aclarar esto, por favor?
2. Por lo que he visto, from common_config import * es el mejor enfoque para mantener la configuración sincronizada.

3. Creo que la mejor manera de hacer esto es algo como la siguiente estructura de directorios:

   main-project/
    conf.py
    documentation.rst
   
    sub-project-1/
       conf.py - imports from main-project/conf.py
       documentation.rst
   
    sub-project-2/
       conf.py - likewise, imports from main-project/conf.py
       documentation.rst

   Luego, para simplemente empaquetar el sub-project-1 o el sub-project-2 , use este comando UNIX:

   sphinx-build main-project/ <output directory> <paths to sub-project docs you want to add>

   De esa manera, no solo se construirá la documentación del proyecto principal, sino que también se agregará la documentación del subproyecto que desea agregar.

   Para empaquetar main-project :

   sphinx-build main-project/ <output directory>

   Estoy bastante seguro de que este esquema funcionará, pero todavía tengo que probarlo.

¡Espero que esto ayude!

Answer 2

Con respecto al punto 2 (incluida la configuración común), estoy usando:

execfile (os.path.abspath("../../common/conf.py"))

Tenga en cuenta que, a diferencia de la estructura de directorios presentada por @DangerOnTheRanger , prefiero mantener un directorio separado para la documentación común, razón por la cual lo common aparece en la ruta anterior.

Mi archivo común / conf.py es un archivo normal de Sphynx. Luego, cada una de las configuraciones de documentación específica incluye ese archivo común y reemplaza los valores según sea necesario, como en este ejemplo:

import sys
import os

execfile (os.path.abspath("../../common/conf.py"))

extensions = [
    ''sphinx.ext.autodoc'',
    ''sphinx.ext.todo'',
    ''sphinx.ext.viewcode'',
]

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

# If true, links to the reST sources are added to the pages.
html_copy_source = False
html_show_sourcelink = False