Documentation Guidelines

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

For more details, see The Sphinx Documentation and Quick reStructuredText.

Sections

Section headings are very flexible in reST. We use the following convention in the Knora documentation based on the Python Documentation Conventions:

  • # (over and under) for parts
  • * (over and under) for chapters
  • = 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:

.. _knora_part::

##########
Knora Part
##########

.. _knora-chapter:

*************
Knora Chapter
*************

This is the chapter documentation.

.. _knora-section:

Knora Section
=============

Knora Subsection
----------------

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

Build the documentation

First install Sphinx. See below.

For the html version of the docs:

sbt sphinx:generateHtml

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

For the pdf version of the docs:

sbt sphinx:generatePdf

open <project-dir>/akka-docs/target/sphinx/latex/AkkaJava.pdf
or
open <project-dir>/akka-docs/target/sphinx/latex/AkkaScala.pdf

Installing Sphinx on OS X

Install Homebrew.

Install Python with Homebrew:

brew install python

Homebrew will automatically add Python executable to your $PATH and pip is a part of the default Python installation with Homebrew.

More information in case of trouble: Homebrew and Python.

Install sphinx:

pip install sphinx

Install the BasicTeX package.

Add texlive bin to $PATH:

export TEXLIVE_PATH=/usr/local/texlive/2015basic/bin/universal-darwin
export PATH=$TEXLIVE_PATH:$PATH

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
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:

export LANG=en_GB.UTF-8
export LC_ALL=en_GB.UTF-8