This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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.

Examples of projects using sphinx

Sphinx http://sphinx-doc.org
Read The Docs https://read-the-docs.readthedocs.org
Projects using sphinx http://sphinx-doc.org/examples.html
sphinxjp.themes.revealjs http://pythonhosted.org/sphinxjp.themes.revealjs
loadconfig http://loadconfig.glidelink.net/docs

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. Also, the filesystem notification tool was upgraded to watchdog, removing another system dependency and making the code more generic and cleaner. With these changes, as of release 0.7.4, sphinxserve is able to run in other platforms as OSX and Windows for example.

Installation

sphinxserve can be installed either as a python package, or as a docker application. On linux and OSX, it can also be installed as a pex python executable

Python executable (PEX)

This is the easiest (no compilation or fancy tooling needed) and smallest (~9 MB) way to install sphinxserve using the excellent PEX tool. In itself, it is a zipfile containing all python package dependencies and only requires the python interpreter. This pex is verified to work at least in Debian>=7, Ubuntu>=14, Centos>=7 and Arch distros on Linux and in Yosemite on OSX.

Linux

System dependencies: glibc linux>=3, python>=2.7,<3 and a web browser supporting websockets (Firefox, Chrome, etc) on Linux:

$ wget -O ~/bin/sphinxserve https://github.com/mzdaniel/sphinxserve/releases/download/0.7.4/sphinxserve-linux
$ chmod 755 ~/bin/sphinxserve

OSX

Yosemite already has all needed dependencies:

$ wget -O ~/bin/sphinxserve https://github.com/mzdaniel/sphinxserve/releases/download/0.7.4/sphinxserve-osx
$ chmod 755 ~/bin/sphinxserve

Python package

Linux system dependencies: glibc linux>=3, python>=2.7,<3, the C toolchain (package names dependent on linux distro) to compile gevent and a web browser supporting websockets. pip automatically downloads sphinxserve and its python dependencies, compiles and builds wheel binary packages as needed and finally install sphinxserve.

OSX system dependencies: Xcode. Verified to work on Yosemite.

Windows system dependencies: Verified to work on Windows 7, python >=2.7,<3 and a web browser supporting websockets with just pip installing.

In all systems:

$ 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 and the ability to run on OSX, Windows and Linux with the same image, assuming proper setup of the docker network and volume. Another advantage is that a running image cannot see your filesystem by default. Sharing directories and which ones is an explicit setup. This method is verified to work on Linux so far.

System dependencies: docker and a web browser supporting websockets.

This installation command automatically downloads sphinxserve image (~40 MB) and creates a small shell script ~/bin/sphinxserve that simplifies the running interface with the following command:

$ docker run mzdaniel/sphinxserve install | bash

Launching

Launching sphinxserve is as simple as:

$ sphinxserve [OPTIONAL_SPHINX_PATH]

By default, it assumes the sphinx project is in the current directory. A sphinx project needs to have the configuration file conf.py, and if not found, sphinxserve will automatically create 2 new files: conf.py and a restructuredtext index.rst.

To change host and/or port, and other options, check the help with:

$ sphinxserve serve --help

Workflow

After launching sphinxserve, it will build the sphinx pages and serve them by default on localhost:8888. To see the rendered documentation, just point your browser to localhost:8888. Any saved changes on rst or txt files will trigger docs rebuild.

Thanks!

Release History

Release History

0.8b1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.4

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sphinxserve-0.7.4-py2-none-any.whl (12.8 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Sep 5, 2015
sphinxserve-0.7.4.tar.gz (9.3 kB) Copy SHA256 Checksum SHA256 Source Sep 5, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development 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