When writing a document with Sphinx, I think that I often execute the make html command to convert the source file (reST) to HTML. I will. After writing for a while, the operation of executing a command every time I change the source file and reloading the browser to check the HTML ... seems complicated.
Python Live Reload (http://livereload.readthedocs.org/en/latest/) allows you to detect file changes and automatically reload your browser. Since the setting script is written in Python, the advantage is that if you are writing a document about Python, you do not need to switch heads.
The setting method is different depending on the version, and various APIs are also different. Since version 2.2.1, it is about to be used in Python 3.x, so I will summarize the introduction method.
It is easy to set up by preparing * .envrc * and * requirements.txt * using direnv.
$ direnv allow .
$ pip install -r requirements.txt
.envrc
# for Python 2.7
#PYVENV_DIR=$HOME/.pyvenv/sphinx-py27
#PYVENV="virtualenv --distribute"
# for Python 3.4
PYVENV_DIR=$HOME/.pyvenv/sphinx-py34
PYVENV=pyvenv-3.4
[ -d $PYVENV_DIR ] || $PYVENV $PYVENV_DIR
source $PYVENV_DIR/bin/activate
requirements.txt
Sphinx
livereload
You can now access the Sphinx and livereload packages and commands by navigating to this directory in your terminal.
Next, prepare * server.py * for your WSGI application. It is convenient to set the execution bit because the number of types at startup is small.
server.py
#!/usr/bin/env python
from livereload import Server, shell
server = Server()
server.watch('**/*.rst', shell('make html'))
server.serve(open_url=False)
Run the script to start the server. ʻIf you give True to the open_url` argument, the page will open in your default browser when the server starts.
$ ./server.py
After that, if you edit the reST source file of the document normally, make html will be executed when the file is saved and the browser will be updated. If you want to insert other processing, you can write it in Python, so you can handle most things.
Python LiveReload makes writing documentation in Sphinx a breeze. You can do the same with Watchdog, but LiveReload will even reload your browser. I'm happy.
Both Python 2.x and Python 3.x are supported, and the implementation may be subtle or not supported in the first place, but if you build it manually every time you edit the source file, It's worth the introduction.
It can also be used as a general-purpose LiveReload server. You can use the livereload command to specify a directory for distribution, which is useful for editing a little HTML.
Recommended Posts