Najprostszy sposób uruchomienia Sphinx na jednym pliku python

Question

Mamy konfigurację Sphinx, która wygeneruje mnóstwo dokumentów HTML dla całego naszego kodu. Czasami pracuję nad jednym plikiem i po prostu chciałbym zobaczyć wyjście HTML z tego pliku, aby upewnić się, że mam odpowiednią składnię bez uruchamiania całego pakietu.

Szukałem najprostszego polecenia, jakie mogłem uruchomić w terminalu, aby uruchomić sfinks na tym jednym pliku i jestem pewien, że informacje tam są, ale nie widziałem.

Answer 1

Sphinx przetwarza pliki REST (nie bezpośrednio pliki Python). Pliki te mogą zawierać odniesienia do modułów Pythona (gdy używasz autodoc). Moje doświadczenie jest takie, że jeśli tylko pojedynczy moduł Pythona został zmodyfikowany od czasu ostatniej pełnej kompilacji wyjściowej, Sphinx nie odtwarza wszystkiego; tylko plik reST, który "ściąga" ten konkretny moduł Pythona, jest przetwarzany. Pojawia się komunikat o nazwie updating environment: 0 added, 1 changed, 0 removed.

Aby jawnie przetwarzać pojedynczy plik REST, należy określić go jako argument do sphinx-build:

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

Answer 2

ten odbywa się w dwóch etapach:

1. Generuj plik RST z modułem Pythona z sphinx- apidoc.
2. Generowanie html z pliku rst za pomocą sphinx-build.

Ten skrypt wykonuje pracę. Nazywają go stojąc w tym samym katalogu jako moduł i dostarczyć go z nazwą pliku modułu:

#!/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"