Documentation Guidelines

The Akka documentation uses reStructuredText as its markup language and is built using Sphinx.

Sphinx

More to come...

reStructuredText

More to come...

Sections

Section headings are very flexible in reST. We use the following convention in the Akka documentation:

# (over and under) for module headings
= for sections
- for subsections
^ for subsubsections
~ for subsubsubsections

Cross-referencing

Sections that may be cross-referenced across the documentation should be marked with a reference. To mark a section use .. _ref-name: before the section heading. The section can then be linked with :ref:`ref-name`. These are unique references across the entire documentation.

For example:

.. _akka-module:

#############
 Akka Module
#############

This is the module documentation.

.. _akka-section:

Akka Section
============

Akka Subsection
---------------

Here is a reference to "akka section": :ref:`akka-section` which will have the
name "Akka Section".

Build the documentation

First install Sphinx. See below.

Building

cd akka-docs

make html
open _build/html/index.html

make pdf
open _build/latex/Akka.pdf

Installing Sphinx on OS X

Install Homebrew

Install Python and pip:

brew install python
/usr/local/share/python/easy_install pip

Add the Homebrew Python path to your $PATH:

/usr/local/Cellar/python/2.7.1/bin

More information in case of trouble: https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python

Install sphinx:

pip install sphinx

Add sphinx_build to your $PATH:

/usr/local/share/python

Install BasicTeX package from: http://www.tug.org/mactex/morepackages.html

Add texlive bin to $PATH:

/usr/local/texlive/2010basic/bin/universal-darwin

Add missing tex packages:

sudo tlmgr update --self
sudo tlmgr install titlesec
sudo tlmgr install framed
sudo tlmgr install threeparttable
sudo tlmgr install wrapfig
sudo tlmgr install helvetic
sudo tlmgr install courier

Link the akka pygments style:

cd /usr/local/Cellar/python/2.7.1/lib/python2.7/site-packages/pygments/styles
ln -s /path/to/akka/akka-docs/themes/akka/pygments/akka.py akka.py

Contents