在一个 python 文件上运行 Sphinx 的最简单方法
Posted
技术标签:
【中文标题】在一个 python 文件上运行 Sphinx 的最简单方法【英文标题】:Simplest way to run Sphinx on one python file 【发布时间】:2012-05-21 20:34:11 【问题描述】:我们有一个 Sphinx 配置,它将为我们的整个代码库生成大量 html 文档。有时,我正在处理一个文件,我只想查看该文件的 HTML 输出,以确保在不运行整个套件的情况下获得正确的语法。
我寻找了可以在终端中运行的最简单的命令,以便在这个文件上运行 sphinx,我确定信息就在那里,但我没有看到它。
【问题讨论】:
【参考方案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
【讨论】:
这会导致 sphinx 1.0.3 出现错误(撰写本文时的最新版本)。错误:源目录不包含 conf.py 文件。 @ideasman42:是的,要使该命令正常工作,当前目录中必须有一个 conf.py 文件。您可以使用-c
选项显式指定 conf.py 的位置。【参考方案2】:
这分两步完成:
-
使用 sphinx-apidoc 从 python 模块生成 rst 文件。
使用 sphinx-build 从 rst 文件生成 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 的最简单方法的主要内容,如果未能解决你的问题,请参考以下文章
最终用户将如何访问 Sphinx 为 Python 包生成的文档?