Manera más simple de ejecutar Sphinx en un archivo de Python

Tenemos una configuración de Sphinx que generará una gran cantidad de documentos HTML para todo nuestro código base. A veces, estoy trabajando en un archivo y me gustaría ver el resultado HTML de ese archivo para asegurarme de tener la sintaxis correcta sin ejecutar todo el paquete.Manera más simple de ejecutar Sphinx en un archivo de Python

Busqué el comando más simple que pude ejecutar en un terminal para ejecutar sphinx en este archivo y estoy seguro de que la información está ahí pero no la vi.

Fuente

2012-05-21 Matthew Lund

Sphinx procesa archivos reST (no archivos Python directamente). Esos archivos pueden contener referencias a módulos de Python (cuando usa autodoc). Mi experiencia es que si solo se modificó un solo módulo de Python desde la última generación completa de resultados, Sphinx no regenera todo; solo se procesa el archivo reST que "extrae" ese módulo de Python en particular. Hay un mensaje que dice updating environment: 0 added, 1 changed, 0 removed.

Para procesar explícitamente un único archivo de descanso, se especifica como un argumento a sphinx-build:

sphinx-build -b html -d _build/doctrees . _build/html your_filename.rst

Fuente

2012-05-28 17:52:30 mzjn

Esto da un error con sphinx 1.0.3 (último en el momento de la escritura). Error: El directorio de origen no contiene el archivo conf.py. – ideasman42

@ ideasman42: Sí, para que ese comando exacto funcione, debe haber un archivo conf.py en el directorio actual. Puede especificar la ubicación de conf.py explícitamente con la opción ['-c'] (http://sphinx.pocoo.org/invocation.html#cmdoption-sphinx-build-c). – mzjn

Esto se hace en dos pasos:

generar el archivo desde el primer módulo de Python con sphinx- apidoc.
Genera html desde el primer archivo con sphinx-build.

Este script hace el trabajo. Llámelo mientras está en el mismo directorio que el módulo y proporcione el nombre de archivo del módulo:

#!/bin/bash 
# Generate html documentation for a single python module 

PACKAGE=${PWD##*/} 
MODULE="$1" 
MODULE_NAME=${MODULE%.py} 

mkdir -p .tmpdocs 
rm -rf .tmpdocs/* 
sphinx-apidoc \ 
    -f -e --module-first --no-toc -o .tmpdocs "$PWD" \ 
    # Exclude all directories 
    $(find "$PWD" -maxdepth 1 -mindepth 1 -type d) \ 
    # Exclude all other modules (apidoc crashes if __init__.py is excluded) 
    $(find "$PWD" -maxdepth 1 -regextype posix-egrep \ 
     ! -regex ".*/$MODULE|.*/__init__.py" -type f) 
rm .tmpdocs/$PACKAGE.rst 
# build crashes if index.rst does not exist 
touch .tmpdocs/index.rst 
sphinx-build -b html -c /path/to/your/conf.py/ \ 
    -d .tmpdocs .tmpdocs .tmpdocs .tmpdocs/*.rst 

echo "**** HTML-documentation for $MODULE is available in .tmpdocs/$PACKAGE.$MODULE_NAME.html"

Fuente

2015-05-01 05:10:35

Manera más simple de ejecutar Sphinx en un archivo de Python

Respuesta

Cuestiones relacionadas