Sphinx：强制重建 html，包括 autodoc答案

【问题标题】：Sphinx: force rebuild of html, including autodocSphinx：强制重建 html，包括 autodoc
【发布时间】：2014-01-09 11:53:42
【问题描述】：

目前，每当我运行sphinx-build 时，只有在源文件发生更改时才会选择并使用内联文档字符串。我尝试使用-a 开关调用sphinx-build，但这似乎没有效果。

如何强制完全重建 HTML 输出并强制执行 autodoc？

【问题讨论】：

标签： python python-sphinx sphinx-apidoc

【解决方案1】：

如果-E option 与-a 一起使用，它似乎可以工作。我将它添加到我的Makefile 中的html 目标中，现在无需更新任何.rst 文件即可获取文档字符串中的更改。

【讨论】：

【解决方案2】：

我不使用 sphinx-build 但使用 make html 我总是在我的源文件上使用touch *.rst。然后使 html 可以拾取更改。

【讨论】：

make clean 从构建目录中删除文件，然后后面的make html 构建新文件。
触摸源文件可能会产生副作用。这可能会使查看哪些文件已更改变得更加困难。
@Henrik 我需要在哪里运行这些命令？在 powershell 和 git bash shell 中它什么也不做
@AndreasL。 make 必须在使用前安装。在 Powershell 中安装它以 here 为例进行说明。
@AndreasL。还有一个make.bat 文件，可以在Windows 上使用。

【解决方案3】：

我使用make 的clean 子命令强制重建文档（正如@Henrik 在他的评论中所述）。

您可以将其作为单独的命令发出：

make clean
make html

或者可以组合命令：

make clean html

【讨论】：

请原谅我的不知情，但我需要在哪里发出这些命令？
@AndreasL。在terminal 中，在 doc 文件夹中，您将拥有 make.bat 文件。

【解决方案4】：

对于 Windows 用户，在 this answer 的基础上使用 -E -a 选项，我使用新选项更新了 make.bat 文件

> ./make.bat clean

make.bat

@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
    set SPHINXBUILD=sphinx-build
)

set SOURCEDIR=source
set BUILDDIR=build
set SPHINXOPTS=
set TARGET=%1

if "%1" == "" goto help
if "%1" == "clean" goto clean
goto :run

:clean
echo.CLEAN BUILD with -E -a 
set %TARGET% = "html"
set %SPHINXOPTS% = "-E -a"

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
    echo.
    echo.The 'sphinx-build' command was not found! Make sure you have Sphinx
    echo.installed, then set the SPHINXBUILD environment variable to point
    echo.to the full path of the 'sphinx-build' executable. Alternatively you
    echo.may add the Sphinx directory to PATH.
    echo.
    echo.If you do not have Sphinx installed, grab it from
    echo.http://sphinx-doc.org/
    
    exit /b 1
)

:run
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
echo.   clean to make clean. 
:end
popd

【讨论】：