Documentation Guidelines

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".

Building

For the html version of the docs:

sbt sphinx:generate-html
 
open <project-dir>/akka-docs/target/sphinx/html/index.html

For the pdf version of the docs:

sbt sphinx:generate-pdf
 
open <project-dir>/akka-docs/target/sphinx/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/2012basic/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