在一个python文件上运行Sphinx的最简单方法

我们有一个Sphinx配置，它将为我们的整个代码库生成一大堆HTML文档。有时候，我正在处理一个文件，我只想看到该文件的HTML输出，以确保无需运行整个套件即可获得正确的语法。在一个python文件上运行Sphinx的最简单方法

我寻找最简单的命令，我可以在终端上运行这个文件上的狮身人面像，我确信信息已经出现在那里，但我没有看到它。

2012-05-21 Matthew Lund

狮身人面像处理reST文件（不是直接Python文件）。这些文件可能包含对Python模块的引用（当您使用autodoc时）。我的经验是，如果自上一次完整的输出构建以来只修改了一个Python模块，则Sphinx不会重新生成所有内容;只有“拉入”特定Python模块的reST文件才被处理。有一条消息说updating environment: 0 added, 1 changed, 0 removed。

要明确处理单个的reST文件，指定它作为参数传递给sphinx-build：

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

来源

2012-05-28 17:52:30 mzjn

这给出了sphinx 1.0.3（最新的写作时）的错误。错误：源目录不包含conf.py文件。 – ideasman42

@ ideasman42：是的，要完成该命令，必须在当前目录中有一个conf.py文件。您可以使用['-c']（http://sphinx.pocoo.org/invocation.html#cmdoption-sphinx-build-c）选项明确指定conf.py的位置。 – mzjn

这是分两步进行：

生成与sphinx-的Python模块第一个文件apidoc。
使用sphinx-build从第一个文件生成html。

该脚本完成这项工作。在站在与模块相同的目录中时调用它，并为其提供模块的文件名：

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

来源

2015-05-01 05:10:35

在一个python文件上运行Sphinx的最简单方法

回答

相关问题