Inclusión de documentación externa en un proyecto de Sphinx

Question

Mantenemos una documentación bastante grande con Sphinx en SVN.

Como parte de la salida generada, nos gustaría incluir las notas de la versión de los módulos de Python relacionados como contenido principal (¡no como hipervínculo!). Las notas de la versión de los módulos externos también se mantienen en SVN. ¿Hay alguna forma de Sphinx-ish de extraer las partes de la documentación de otras fuentes (SVN)? Ok, usar SVN Externals es una forma de resolver el problema, pero tal vez no la forma más inteligente ... ¿alguna mejor opción?

Answer 1

Las dos opciones que se me ocurren son:

1. Agregar un enlace svn:externals al proyecto a distancia (que ya conoce).
2. Amplíe Sphinx con una directiva personalizada para incluir archivos de repositorios de subversión remotos.

No soy un experto en Sphinx internals, pero pude improvisar una extensión rápida que integra archivos de un repositorio de subversión remoto.

La extensión agrega una directiva svninclude que toma 1 argumento, la url del repositorio donde se encuentran sus documentos. Comprueba este repositorio en un directorio temporal _svncache ubicado en la raíz del proyecto, y luego procede a leer los contenidos de cada archivo e insertarlos en la máquina de estados del analizador.

Aquí está el código para la extensión svninclude.py. Está simplificado en exceso y no tiene errores de verificación en este momento. Si va a poner en práctica esta que me haga saber y me puede proporcionar algunos consejos adicionales si se queda atascado:

import os, re, subprocess, sys 
from docutils import nodes, statemachine 
from docutils.parsers.rst import directives 
from sphinx.util.compat import Directive, directive_dwim 

class SvnInclude(Directive): 

    has_content = True 
    required_arguments = 1 
    optional_arguments = 0 
    final_argument_whitespace = False 

    def _setup_repo(self, repo): 
     env = self.state.document.settings.env 
     path = os.path.normpath(env.doc2path(env.docname, base=None)) 
     cache = os.path.join(os.path.dirname(path), '_svncache') 
     root = os.path.join(cache, re.sub('[\W\-]+', '_', repo)) 
     if not os.path.exists(root): 
      os.makedirs(root) 
     subprocess.call(['svn', 'co', repo, root]) 
     return root 

    def run(self): 
     root = self._setup_repo(self.arguments[0]) 
     for path in self.content: 
      data = open(os.path.join(root, path), 'rb').read() 
      lines = statemachine.string2lines(data) 
      self.state_machine.insert_input(lines, path) 
     return [] 

def setup(app): 
    app.add_directive('svninclude', directive_dwim(SvnInclude)) 

Aquí se muestra un ejemplo del margen de beneficio que le incluye en su index.rst (o este archivo):

.. svninclude:: http://svn.domain.com/svn/project 

    one.rst 
    doc/two.rst 

donde los caminos one.rst y doc/two.rst son en relación con la url subversión, por ejemplo http://svn.domain.com/svn/project/one.rst.

Por supuesto, desea empaquetar el svninclude.py y obtenerlo instalado en su ruta de Python. Esto es lo que hice para probarlo:

1. Agregado 'svninclude' a la lista extensions en source/conf.py.
2. Colocado svninclude.py en la raíz del proyecto.

Entonces corrieron:

% PYTHONPATH=. sphinx-build -b html ./source ./build