Posts Tagged ‘sphinx’

A bit of documentation

(Most up-to-date version is located in the repository on bitbucket)

Sphinx comments/fixes web application

Sphinx provides you with a feature of building your documentation as a web application, which gives you a way to interact with your users.

Users are permitted to submit comments as well as their fixes for the documentation. Developers have additional rights of deleting comments/fixes and committing fixes to the documentation repository.

Building a webapp along with documentation

Building your documentation along with a web application, which will serve it, is almost as simple as building the documentation itself.

1. Start a new Sphinx project:

$ mkdir sphinx-project

$ cd sphinx-project

$ sphinx-quickstart

[ …usual sphinx-quickstart questions… ]

2. The documentation is empty as for now. Create at least one file with some content. Now, you can build a webapp which will serve your documentation:

$ make webapp


Build finished. The webapp HTML pages are in _build/webapp.

3. Run the server:

$ cd _build/webapp/

$ python

Running at…

OK, there it goes. Now you can check it with web browser!

The webapp configuration file

The variables and values of webapp.conf file are based on file.

NOTE: Always change the values of variables in file.

  • licence – A name of the licence for fixes submitted by the users. Default is ‘BSD’.
  • reporoot – The name of a directory in which the repository files should be located in build directory. Default is ‘repo’.
  • repodir – If the documentation is located in a subdirectory of a repository, this should be a directory name of the documentation. For example, when the files for Sphinx are copied/cloned to reporoot directory, the directory for documentation in the repository is: _build/webapp/repo/doc/, because the documentation for Sphinx is held in sphinx/doc directory. Default is doc, which works well for Sphinx, but may fail for your project. Please, change it accordingly.
  • repopath – This variable is only visible in webapp.conf file. Its value is created by joining reporoot and repodir values.
  • reposums – A filename for MD5 sums of files from the repository. Default is reposums.pkl.
  • piddbfile – A filename for a database which sorts paragraphs by repository filename and paragraph ID. Default is piddb.pkl.

File structure of the build

After building your documentation, the _build/webapp/ directory gets populated with a number of directories and files.


  • comments – a database for all the comments added to any paragraph.
  • fixes – a database for all the fixes added to any paragraph.
  • openidstore – OpenID logging database
  • html – HTML templates used by the webapp
  • public – your documentation generated by Sphinx
  • repo – source files of your documentation in a repository
  • xapian_db – a database for Xapian search engine


  • – a simple WSGI server, useful for testing purposes
  • webapp.conf – a configuration file for the webapp (based on values from Sphinx’s file
  • developers.txt – a list of OpenIDs of users who should be granted developer’s rights
  • piddb.pkl – a database of paragraphs sorted by filename and paragraph ID
  • reposums.pkl – a database of MD5 sums for files in repo directory. Whenever a sum is not matching reality, the source file is rebuilt.

All for now, folks!