Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

sphinxserve renders sphinx docs monitoring file changes

Project Description

sphinxserve is a tool to effectively document projects

Since the internet adopted HTML, many communities are trying to find ways to write web pages in ways that can be pleasantly readable and writable. In our python community, reStructuredText and Sphinx have been created to author beautiful documentation. The goal of sphinxserve is to make them more accessible, interactive, and convenient to use.

Design considerations

sphinxserve was originally conceived as a Python and Linux project that can visualize sphinx document modifications in real time while working on them. At its core, sphinxserve uses the awesome projects gevent to provide concurrency and event coordination, flask for web communication, Sphinx for reStructucturedText rendering and of course Python. sphinxserve used to control browser reloading with xdotool, introducing a complex system tool dependency. On release 0.7, sphinxserve decouples from this system dependency using instead flask-sockets python package. The tradeoff here was to temporarily drop python3 support until the gevent ecosystem officially supports python3 which should be soon. sphinxserve also upgraded its filesystem notification tool to watchdog, removing another system dependency and making the code more generic, cleaner and closer to run in other operating systems.


sphinxserve can be installed either as a python package, or as a docker application. A pex python executable will be available.

Python package

System dependencies: python==2.7, pip>=7, the C toolchain (package names dependent on linux distro) to compile gevent and a web browser.

pip automatically downloads sphinxserve and its python dependencies, compiles and builds wheel binary packages as needed and finally install sphinxserve using:

pip install sphinxserve

Docker application

Docker is an extraordinary tool that simplifies the entire dependency tree by including it in a system image. This makes the installation experience much more pleasant.

System dependencies: docker and a browser

This installation command automatically downloads sphinxserve image and creates a small shell script ~/bin/sphinxserve that simplifies the running interface:

$ docker run mzdaniel/sphinx install | bash


Assumming your sphinx project is in ~/docproj (containing and ~/bin is in your shell $PATH:

$ sphinxserve ~/docproj


After launching sphinxserve, it will build the sphinx pages and serve them by default on localhost:8888. Any saved changes on rst or txt files will trigger docs rebuild.

Working in a Restructured text project

Lets put together all the pieces. A sphinx project needs at minimum 2 files: the project file and a restructuredtext (rst) index file index.rst:

cat > << EOF
master_doc = 'index'

cat > index.rst << 'EOF'
My awesome sphinx project

This is my first attempt to use `My awesome sphinx project`_

At this point we can browse our project on localhost:8888 with just:



Release History

This version
History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Hash SHA256 Hash Help Version File Type Upload Date
(11.5 kB) Copy SHA256 Hash SHA256
2.7 Wheel Aug 11, 2015
(8.3 kB) Copy SHA256 Hash SHA256
Source Aug 11, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting