Write documentation in Sphinx with Python Livereload

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.

Environment setting by direnv

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.

setting file

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.

in conclusion

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

Write documentation in Sphinx with Python Livereload
Create Python project documentation in Sphinx
Automatically build Python documentation with Sphinx
Automatically create Python API documentation with Sphinx
Write Python in MySQL
Write Pandoc filters in Python
Scraping with selenium in Python
Working with LibreOffice in Python
Scraping with chromedriver in python
Write beta distribution in Python
Debugging with pdb in Python
Write python in Rstudio (reticulate)
Working with sounds in Python
Scraping with Selenium in Python
Write letters in the card illustration with OpenCV python
Scraping with Tor in Python
Tweet with image in Python
Combined with permutations in Python
Let's write python with cinema4d.
Write to csv with Python
Compile Sphinx documentation with Wercker
Number recognition in images with Python
Write a binary search in Python
Testing with random numbers in Python
GOTO in Python with Sublime Text 3
Write JSON Schema in Python DSL
Working with LibreOffice in Python: import
[Python] Write to csv file with Python
Scraping with Selenium in Python (Basic)
CSS parsing with cssutils in Python
Write an HTTP / 2 server in Python
Write AWS Lambda function in Python
Numer0n with items made in Python
Write A * (A-star) algorithm in Python
Open UTF-8 with BOM in Python
Use rospy with virtualenv in Python3
Write selenium test code in python
Write a pie chart in Python
Write a vim plugin in Python
Use Python in pyenv with NeoVim
Write a depth-first search in Python
Heatmap with Dendrogram in Python + matplotlib
Read files in parallel with Python
Password generation in texto with python
Use OpenCV with Python 3 in Window
Until dealing with python in Atom
Write C unit tests in Python
Get started with Python in Blender
Write a batch script with Python3.5 ~
Working with DICOM images in Python
Get additional data in LDAP with python
Spiral book in Python! Python with a spiral book! (Chapter 14 ~)
Try logging in to qiita with Python
Stress Test with Locust written in Python
Python3> in keyword> True with partial match?
Exclusive control with lock file in Python
Device monitoring with On-box Python in IOS-XE
Write the test in a python docstring
Try working with binary data in Python
Draw Nozomi Sasaki in Excel with python
Tips for dealing with binaries in Python