Sphinx: force rebuild of html, including autodoc

Question

Currently, whenever I run sphinx-build, only when there are changes to the source files are the inline docstrings picked up and used. I've tried calling sphinx-build with the -a switch but this seems to have no effect.

How can I force a full rebuild of the HTML output and force autodoc execution?

Answer 1

It seems to work if the -E option is used along with -a. I added it to the html target in my Makefile and now changes in docstrings are picked up without updating any .rst files.

Answer 2

I use the clean sub-command of make to force a rebuild of the documentation (as @Henrik stated in his comment).

You can issue it as a separate command:

make clean
make html

Or the commands can be combined:

make clean html

Answer 3

I do not use sphinx-build but with make html I always do touch *.rst on my source files. Then make html can pickup changes.

Answer 4

For Windows users, building on this answer to use -E -a option, I updated the make.bat file with the new option

> ./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