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

Question

Tenemos un proyecto de varios módulos documentado con la (excelente) Sphinx. Nuestra configuración no es diferente de una described on the mailing list. En general, esto works great! Pero tenemos algunas preguntas sobre hacerlo:

1. Las tablas de contenido del submódulo incluirán enlaces de índice. En el mejor de los casos, estos se vincularán con los índices incorrectos. (En el peor de los casos esto parece desencadenar un error en Sphinx, pero estoy usando la versión de desarrollo, así que es razonable). ¿Hay alguna manera de generar enlaces de índice solo para el árbol de arriba?

2. ¿Existen mejores prácticas para mantener sincronizada la configuración de Sphinx entre varios proyectos? Podría imaginarme hackear algo alrededor de from common_config import *, pero me interesan otros enfoques.

3. Mientras estamos en ello, la cuestión planteada en el puesto de la lista de correo (alternativa a los enlaces simbólicos docs subproyecto?), Nunca fue respondida. No es importante para mí, pero puede ser importante para otros lectores.

Answer 1

1. no estoy seguro de lo que quiere decir con esto. El proyecto index parece estar bien. ¿Podría aclarar sobre 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 parecido a 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, a solo paquete sub-project-1 o sub-project-2, utilice este comando UNIX:

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

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

   Para empaquetar main-project:

   sphinx-build main-project/ <output directory> 
   

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

Hope this helps!

Answer 2

En cuanto al punto 2 (incluyendo 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 presentado por @DangerOnTheRanger, prefiero mantener un directorio independiente para documentación común, por eso common aparece en la ruta anterior.

Mi archivo common/conf.py es un archivo Sphynx normal. A continuación, cada uno de la configuración de la documentación específica que incluye el archivo común y omite 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