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.
Installation
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
Launching
Assumming your sphinx project is in ~/docproj (containing conf.py) and ~/bin is in your shell $PATH:
$ sphinxserve ~/docproj
Workflow
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 conf.py and a restructuredtext (rst) index file index.rst:
cat > conf.py << EOF master_doc = 'index' EOF cat > index.rst << 'EOF' My awesome sphinx project ========================= This is my first attempt to use `My awesome sphinx project`_ EOF
At this point we can browse our project on localhost:8888 with just:
sphinxserve
Thanks!
Georg Brandl & David Goodger for Sphinx and reStructuredText
Denis Bilenko, Armin Rigo & Christian Tismer for Gevent and Greenlet
Armin Ronacher for Flask
Jeffrey Gelens & Kenneth Reitz for gevent websocket and flask sockets
Yesudeep Mangalapilly for watchdog
Eric Holscher for Read The Docs
Brian Wickman for PEX
Mark Otto, Jacob Thornton & Ryan Roemer for Bootstrap sphinx bootstrap
Hakim El Hattab & tell-k for Revealjs and sphinx revealjs
Solomon Hykes, Jerome Petazzoni and Sam Alba for Docker
The awesome Python, Linux and Git communities
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxserve-0.7-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0364e0c6b12cbdcd651eb5d1c7993a5514eda0c596a064d3d33968708c8b3ba |
|
MD5 | f3b9ce61afbdb1fadb2c8a9cdb83c488 |
|
BLAKE2b-256 | 37a46fbc156a33b69a9c6e54ba0445821cfbb222b5c7b8ced4936a68fa1dada6 |