DocServer (for lack of a beter name)
This is a small server built on the Flask web framework. Its primary purpose is to listen for HTTP POST requests sent by the post-commit hooks of a revision control system. Upon receiving such a request, it will check out the latest version of the source code and build static HTML content such as documentation. The static content will then be served for users to browse.
Currently the server is hardcoded in such a way that it responds to POST requests sent by GitHub and builds Sphinx documentation. The source code has been set up with the aim of eventually generalizing to any combination of a version control system and static content generator.
Flask is used as a web framework for handling POST requests and serving documentation. CSS stylesheets are generated from SASS using the Compass framework. These two dependencies may be resolved using the Python and Ruby package managers:
pip install flask gem install compass
The SASS source code in the
compass directory must be compiled to CSS in the
static/css directory before the app may be launched. This may be done by:
cd DocServer compass compile
Settings which control how
compass builds CSS may be tweaked by editing the
Currently, the procedure for launching the app in a development environment is a little wonky (apologies!), it goes like this:
export PYTHONPATH=$PYTHONPATH:/path/to/DocServer cd DocServer python doc_server.py
Upon launch, the server will perform a checkout and build of all projects listed
PROJECTS hash contained in the
config.py file. Currently the
checkout process is tailored to work with GitHub and the build process is
tailored to work with Sphinx
The server consists of three core components:
doc_server.py: This Python module contains the main Flask application and handles processing of things such as GET and POST requests.
doc_manager.py: This Python module controls how source code is checkout out and how static content is built.
utils.py: This Python module contains miscellaneous functions that support the activities conducted by the other modules.
The current state of the code is that of an "alpha" release--- i.e. things are held together with spit and duck--tape and many poor design decisions have been made in the interest of getting things up and running as quickly as possible.
- Logging messages! Currently the app makes no attempt to log any special
activities. Logs of the following events are essential:
- POST requests received by the app.
- Results of documentation building operations. In particular, logs of warning and error messages for programs such as Sphinx would be nice.
- Remove auto-checkout of projects on app startup. This should be done by a separate maintenance script. In Rails applications this is handled by the rakefile. Paver would be the obvious choice for Python.
- Currently projects are checked out and built inside of the DocServer Python
module. This is a Bad Thing in general and limits the module to supporting
only one distinct server instance. This can be remedied by:
- Making the location of project build and static content directories configurable.
- Moving the configuration files out of the module and allowing their location to be passed using environment variables.