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?

score 21 · Accepted Answer · edited Sep 04 '18 at 16:53

21

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.

edited Sep 04 '18 at 16:53

Henrik

2,771
1
23
33

answered Jan 09 '14 at 13:38

J. Katzwinkel

1,923
16
22

score 11 · Answer 2 · answered Oct 20 '20 at 17:51

11

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

answered Oct 20 '20 at 17:51

Fiver

9,909
9
43
63

Excuse my unknowingness, but WHERE do I need to issue these commands? – Andreas L. Jun 15 '21 at 14:16
@AndreasL. in `terminal`, in the doc folder you will have `make.bat` file. – suhailvs Sep 22 '21 at 04:41

score 6 · Answer 3 · answered Mar 03 '14 at 08:33

6

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.

answered Mar 03 '14 at 08:33

Darek

2,861
4
29
52

16

`make clean` removes files from the build directory, then a following `make html` builds new files. – Henrik Sep 05 '18 at 16:03
1

Touching the source files can have side-effects. It could make it harder to see what files have changed. – intotecho Nov 19 '20 at 23:31
@Henrik where do I need to run these commands? In powershell and git bash shell it does not do anything – Andreas L. Jun 15 '21 at 14:17
1

@AndreasL. `make` must be installed before using it. Installing it in Powershell is explained [here](https://superuser.com/a/808818) for example. – Henrik Jun 16 '21 at 16:57
@AndreasL. There is also a `make.bat` file, which you can use on Windows. – Henrik Jun 16 '21 at 17:03
@AndreasL. You have to be in your project directory to run the commands. You might have a look at [Getting Started – Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/quickstart.html) – Henrik Jun 17 '21 at 09:06

score -2 · Answer 4 · answered Nov 20 '20 at 05:25

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

Sphinx: force rebuild of html, including autodoc

4 Answers4

Linked