Process Overview

1. (once) setup sphinx documentation project with sphinx-quickstart
2. create static content in reStructured Text (rst) files
3. let antiweb create dynamic content from source files into rst files
4. run sphinx to create documentation from rst sources

Bootstrap With sphinx-quickstart

• navigate to
• sphinx-quickstart
  • usually ok to accept default values

Optional: Add Graphviz Support

• edit conf.py in sphinx project’s source folder

• add graphviz to the extensions list:

  extensions = ['...', 'sphinx.ext.graphviz']
  

Create Dynamic Content with Antiweb

antiweb can process your Python, C++, C, C#, Clojure and rst files. If you would like to add other languages take a look at the antiweb documentation.

Processing the files

You will most likely have a project consisting of more than one file. Fortunately that occasion is no problem for antiweb.

antiweb.py /path/to/project -r

This snippet will recursively process files in /path/to/project and put them into the directory you are currently working in. To put them in a seperate folder, use:

antiweb.py /path/to/project -r -o foldername

A folder will be created in your working directory and the processed files will be stored in there.

Final step: Create the documentation

Make sure all of your .rst files are stored inside the source folder and that they are registered inside the index.rst (which is also located inside your source folder)

The only thing to do now is to execute:

make html

Sphinx should now be processing your files and put the finished documentation inside the build folder. From now on, only changed documents will be processed by Sphinx. If you would like Sphinx to process all files everytime you run Sphinx, you have to edit the make.bat file and change:

set ALLSPHINXOPTS= -d %BUILDDIR%/doctrees %SPHINXOPTS% source

to

set ALLSPHINXOPTS=-E -d %BUILDDIR%/doctrees %SPHINXOPTS% source

Auto-Update Daemon Mode

• alternatively, start
  • antiweb in daemon mode (option -d)
  • Sphinx in livehtml mode (make livehtml)
• then, changes to a source file are automatically first transformed by antiweb into an rst
• Sphinx then automatically updates the documentation from the changed rst source

doc_server

• the doc_server system (see subdirectory doc_server) provides a simple configurable setup to start several daemon documentation systems
• edit doc_locations.txt and then invoke server_start.bat