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 server.py

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 conf.py file.

NOTE: Always change the values of variables in conf.py 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


  • server.py – a simple WSGI server, useful for testing purposes
  • webapp.conf – a configuration file for the webapp (based on values from Sphinx’s conf.py 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!


5 responses to this post.

  1. Posted by punchagan on September 19, 2009 at 7:20 am

    First of all, Nice project! I think a lot of people would find this useful.

    I have tried out the latest code on bitbucket, but I’m not able to create a sample sphinx doc folder.
    I have put in a sample rst in the source folder.
    But when I try to build the webapp, using ‘make webapp’, I get the following error –
    No such file or directory ‘~/project/_build/webapp/repo/doc/index.rst’


  2. Hi,

    try to change this line:




    in file _build/webapp/webapp.conf

    It should do the job. If it won’t work – please, let me know 🙂


  3. Posted by punchagan on September 19, 2009 at 12:10 pm

    It works. I just got a sample doc to work. I still need to sort out a few things, though.

    I changed the webapp.conf file as suggested. But I also had to do this, before it worked for me. [sphinx-build checks if the following files/directories exist]

    rm -r _build/webapp/comments/ _build/webapp/html/ _build/webapp/fixes/ _build/webapp/public/_static/



  4. Posted by punchagan on September 19, 2009 at 7:06 pm

    Comments etc. do not work, when my rst file is within a folder. For example if I have chapter1/section1.rst, and chapter1/section2.rst, the html is displayed properly. But when new comments do not get added.
    I’ve tried to look at the code, but didn’t make much progress. Can you help me?


  5. Posted by punchagan on September 20, 2009 at 11:50 am

    I did this little change to solve that problem. I’m not sure if it breaks anything else, but doesn’t seem like it.
    207 : elif req.path.endswith(‘/add_comment’):

    Also, can you give me some guidelines on how to go about running the webapp on a publicly accessible server?



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: