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

Running at 127.0.0.1:8000…

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.

Directories:

  • 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

Files:

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

Advertisements