文档指南

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

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _sphinx: http://sphinx.pocoo.org

Sphinx

For more details see The Sphinx Documentation <http://sphinx.pocoo.org/contents.html>_

reStructuredText

For more details see The reST Quickref <http://docutils.sourceforge.net/docs/user/rst/quickref.html>_

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

For the html version of the docs::

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

For the pdf version of the docs::

  1. sbt sphinx:generate-pdf
  2. open <project-dir>/akka-docs/target/sphinx/latex/AkkaJava.pdf
  3. or
  4. open <project-dir>/akka-docs/target/sphinx/latex/AkkaScala.pdf

Installing Sphinx on OS X

Install Homebrew <https://github.com/mxcl/homebrew>_

Install Python and pip:

::

  1. brew install python
  2. /usr/local/share/python/easy_install pip

Add the Homebrew Python path to your $PATH:

::

  1. /usr/local/Cellar/python/2.7.5/bin

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

Install sphinx:

::

  1. pip install sphinx

Add sphinx_build to your $PATH:

::

  1. /usr/local/share/python

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

Add texlive bin to $PATH:

::

  1. /usr/local/texlive/2013basic/bin/universal-darwin

Add missing tex packages:

::

  1. sudo tlmgr update --self
  2. sudo tlmgr install titlesec
  3. sudo tlmgr install framed
  4. sudo tlmgr install threeparttable
  5. sudo tlmgr install wrapfig
  6. sudo tlmgr install helvetic
  7. sudo tlmgr install courier
  8. sudo tlmgr install multirow

If you get the error “unknown locale: UTF-8” when generating the documentation the solution is to define the following environment variables:

::

  1. export LANG=en_US.UTF-8
  2. export LC_ALL=en_US.UTF-8