CHAOS API Documentation

The documentation can be viewed at http://chaos-community.github.io/CHAOS-API-Documentation/.

Build

The documentation is made with Sphinx. To get Sphinx, make sure you have Python installed (with Distribute) and install it via pip

> pip install sphinx

You can install all dependencies automatically with

> pip install -r requirements.txt

Note: Please do not add distribute to requirements.txt, as this breaks our drone.io continous integration for the documentation.

Once you have install Sphinx, you can build the documentation with

> make html

The docs will then be in build/html.

Guide

reStructuredText

Sphinx uses reStructuredText (.rst) as markup language for its pages. A quick guide to reStructuredText can be found here.

Indentation

We use 3 spaces for indentation in the reST source (the same as the Python docs). This, of course, does not apply to code examples inside the reST source/documentation.

Example:

.. module:: MCM

   .. extension:: Object

      .. action:: Get

Repository structure

The master branch (v4) is the "oldest" version, newer versions should be branches that originate in this branch.

This means that documentation that applies to all versions can be committed to master. After that you should run:

> ./update-branches.sh

What this does is basically a rebase of v5 onto the master branch and v6 onto the v5 branch:

> git checkout v5 && git rebase master # rebase v5 onto master
> git checkout v6 && git rebase v5     # rebase v6 onto v5

If find out you need to update v4 but not v5 and v6, you can do the commit to master as usual, and then rebase v5 onto master and then do a git revert <COMMIT_HASH> of the commit that changed v4:

> git commit # The update on v4 (master branch)
> git checkout v5 && git rebase master
> git revert <COMMIT_HASH>
> git checkout v6 && git rebase v5

PHP Portal Client documentation

Install the PHP domain for Sphinx

> pip install sphinxcontrib-phpdomain

Install the http://mark-story.com/posts/view/sphinx-phpdomain-released https://github.com/avalanche123/doxphp

> pear channel-discover pear.avalanche123.com
> pear install avalanche123/doxphp-beta

Autogenerate the API documentation

> cd src/CHAOS/Portal/Client/
> mkdir docs
> for f in $(find . -iname '*.php' -print0); do bf="$(basename $f)"; doxphp < $f | doxphp2sphinx > docs/$bf.rst; done

Caveats

• restructuredText (.rst) does not support nested markup (link)
• To have a non-paragraph linebreak (single instead of double) use |br| (link)

Continuous deployment

drone.io is setup to monitor the Github repository for changes. A push or commit to any of the version branches (master, v4 etc.) will automatically build the documentation of all versions and put them in the gh-pages branch. drone.io is set to run the following commands:

git checkout master
pip install -r requirements.txt --use-mirrors
python create_docs.py --commit
git push https://$TOKEN:@github.com/malthejorgensen/CHAOS-API-Documentation.git gh-pages

This of course assumes that the master branch has a create_docs.py script and a requirements.txt file. Furthermore a Github token login is set up and the token should be put in the TOKEN environment variable on drone.io:

TOKEN=b5836fa...

Credits

Inspired by:

• MongoDB Manual