Automatically build Sphinx documentation when a source file changes

Question

I'm using Sphinx to document one of my projects, and I like to preview my changes in my browser. I want to be able to save some changes to an .rst file, and be able to immediately refresh my browser and see the changes.

Essentially I want to automatically execute a make html whenever one of the .rst files is changed.

score 37 · Answer 1 · edited May 16 '23 at 17:21

You can use sphinx-autobuild. It will also automatically initiate a page refresh in the browser.

It is easy to use, for example:

sphinx-autobuild docs docs/_build/html

or, if you have a separate build dir,

sphinx-autobuild <doc-source-dir> <doc-build-dir>

where <doc-source-dir> is the source directory of your documentation and <doc-build-dir> is the directory where you want the built html files.

score 16 · Answer 2 · answered Dec 10 '13 at 01:28

16

Jacob Kaplan-Moss has a good solution:

pip install watchdog
watchmedo shell-command \
          --patterns="*.rst" \
          --ignore-pattern='_build/*' \
          --recursive \
          --command='make html'

Note, change the pattern to match your suffix. Jacob uses *.txt, but I needed to change it to *.rst.

answered Dec 10 '13 at 01:28

ferrouswheel

3,658
2
24
24

If you using Firefox you could install Auto Reload add-on. – swietyy Jan 12 '14 at 21:52
This worked for me. I altered the command 'make html' to 'make html && xvkbd -window Firefox -text "\Cr"' to get automatic reloading. – Doug Bradshaw Jan 31 '15 at 01:10

score 4 · Answer 3 · answered May 02 '12 at 18:37

4

If you're on a *nix system, you can use inotify to monitor filesystem events and trigger actions.

For example, on ubuntu,

apt-get install inotify-tools

Then run a script like this to listen for events in a given dir

while true
  do
    inotifywait -r -e modify -e move -e create -e delete /tmp/docs | while read line
      do
        echo "file changed; time to run make html"
      done
  done

answered May 02 '12 at 18:37

perrygeo

385
1
14

Instead of using 2 while loops you can also remove the outer loop by adding the `--monitor` (`-m`) switch to `inotifywait`. – F.X. Aug 15 '22 at 13:50

score 0 · Answer 4 · answered Apr 02 '11 at 10:42

0

You can create a macro in you favorite editor that saves the file and opens it in your browser, any text editor can do (geany, gedit, emacs, vi, notepad++...)

answered Apr 02 '11 at 10:42

P2bM

1,038
6
9

2

Not a bad idea... however I'd prefer something more portable. I really want to be able to just run `make html --auto-rebuild` – bradley.ayers Apr 02 '11 at 10:46
well you can always write a script that does that – P2bM Apr 02 '11 at 10:47

Automatically build Sphinx documentation when a source file changes

4 Answers4