A small server, written in Python, for automagically fetching, building and serving up-to-date project documentation
Python Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
compass
projects
static/images
templates
README.rst
__init__.py
config.py
config.rb
doc_manager.py
doc_server.py
utils.py

README.rst

DocServer (for lack of a beter name)

V 0.1-alpha

Overview

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.

Installation

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 config.rb file.

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 in the 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

Design Notes

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.

To Do

  • 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.