raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

add preprocessor for RST docs, see #2461 and #2431

Browse source 
The idea is to filter the sources, replacing @<var>@ occurrences with
the mapping for <var> (which is currently hard-coded). @@ -> @. In order
to make this work, I had to move the doc sources one directory down
(into akka-docs/rst) so that the filtered result could be in a sibling
directory so that relative links (to _sphinx plugins or real code) would
continue to work.

While I was at it I also changed it so that WARNINGs and ERRORs are not
swallowed into the debug dump anymore but printed at [warn] level
(minimum).

One piece of fallout is that the (online) html build is now run after
the normal one, not in parallel.
This commit is contained in:
Roland 2012-09-21 10:47:58 +02:00
parent c0f60da8cc
commit 9bc01ae265
266 changed files with 270 additions and 182 deletions
Download patch file Download diff file Expand all files Collapse all files

149
akka-docs/dev/documentation.rst
View file

@ -1,149 +0,0 @@
.. highlightlang:: rest
.. _documentation:
#########################
Documentation Guidelines
#########################
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
======
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 <https://github.com/mxcl/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