Question

我们有一个Sphinx配置，它将为我们的整个代码库生成大量HTML文档。有时，我正在处理一个文件，我只是希望看到该文件的HTML输出，以确保我在不运行整个套件的情况下获得正确的语法。

我找了一个最简单的命令，我可以在终端上运行这个文件运行sphinx，我确定信息在那里，但我没有看到它。

Answer 1

Sphinx处理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

Answer 2

这分两步完成：

使用sphinx-apidoc从python模块生成第一个文件。
使用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"

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

2 个答案: