The documentation can be viewed at http://chaos-community.github.io/CHAOS-API-Documentation/.
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.
Sphinx uses reStructuredText (.rst) as markup language for its pages. A quick
guide to reStructuredText can be found here.
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
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
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
- restructuredText (
.rst) does not support nested markup (link) - To have a non-paragraph linebreak (single instead of double) use |br| (link)
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...
Inspired by: