README.rst 3.56 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
Documentation Howto
===================

The folders ''sphinx_beginner'' and ''sphinx_intermediate'' are Re-Writes of the documentation 
which was originally done in Word, converted to ReStructuredText.

Here, we're using `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ for writing, and `Sphinx <http://sphinx-doc.org/>`_
to convert the Markup into HTML and PDF ("Sphinx is a tool that makes it easy to create intelligent and beautiful documentation") 

Sphinx uses ``conf.py`` for configuration and provides a convenient Makefile for conversion. 
Just call ``make html`` (``make singlehtml`` creates one single HTML file), or ``make latexpdf`` to run it.
Holger Dinkel's avatar
Holger Dinkel committed
12
The resulting documents will be in ``_build/html/`` or ``_build/latex/``, respectively.
13 14 15

Currently, we do not include the HTML output into git, just the PDF and maybe the singlehtml page.

Holger Dinkel's avatar
Holger Dinkel committed
16
Requirements:
Holger Dinkel's avatar
Holger Dinkel committed
17
^^^^^^^^^^^^^
18 19 20 21

- ReStructuredText https://en.wikipedia.org/wiki/ReStructuredText
- Sphinx >1.1 http://sphinx-doc.org/
- Pygments >1.5  http://pygments.org/
Holger Dinkel's avatar
Holger Dinkel committed
22 23 24
- TexLive >2011 http://www.tug.org/texlive/

Links:
Holger Dinkel's avatar
Holger Dinkel committed
25
^^^^^^
26 27

- `ReST Cheat Sheet <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html>`_
Holger Dinkel's avatar
Holger Dinkel committed
28
- `ReST and Sphinx Primer <http://openmdao.org/dev_docs/documenting/sphinx.html>`_
29
- `Writing Technical Documentation with Sphinx, Paver, and Cog  <http://doughellmann.com/2009/02/writing-technical-documentation-with-sphinx-paver-and-cog.html>`_
Holger Dinkel's avatar
Holger Dinkel committed
30 31 32 33


PS: I've manually updated the Makefiles to do some minor ``sed`` replacement to use the LaTeX package `fancyvrb <http://www.ctan.org/pkg/fancyvrb>`_ for styling
the verbatim boxes; this package should be included in the TeXLive distribution.
34

Holger Dinkel's avatar
Holger Dinkel committed
35 36 37
ToDos:
^^^^^^

Holger Dinkel's avatar
Holger Dinkel committed
38 39 40 41 42 43 44 45
- Features to try out:

  - centered
  - hlist
  - glossary

- Include examples from "Bioinformatics One-Liners"

Holger Dinkel's avatar
Holger Dinkel committed
46
- Proper Use of sectioning:
Holger Dinkel's avatar
Holger Dinkel committed
47 48 49 50 51 52 53

  - '#' with overline, for parts
  - '*' with overline, for chapters
  - '=', for sections
  - '-', for subsections
  - '^', for subsubsections
  - '"', for paragraphs
Holger Dinkel's avatar
Holger Dinkel committed
54

Holger Dinkel's avatar
Holger Dinkel committed
55 56 57
- Better control of verbatim code-blocks:

  - distinguish user input from output (boldface?)
58

Holger Dinkel's avatar
Holger Dinkel committed
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
Change Fonts
^^^^^^^^^^^^
To change the font of the (latex) output, add the respective package to the preamble in conf.py:
For Tex Gyre Termes font:

  ::

    \\usepackage{tgtermes}

For Palatino:

  ::

    \\usepackage[sc]{mathpazo}

For full list of Tex Fonts see the `LaTeX Font Catalog <http://www.tug.dk/FontCatalogue/seriffonts.html>`_ ...

76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
syntax highlight styling
^^^^^^^^^^^^^^^^^^^^^^^^
To change the formatting of verbatim code blocks (which are highlighted using Pygments), you can create a style file and reference this 
in 'conf.py':

  :: 

    pygments_style = 'lsi.lsiClass'

This is the content of the file lsi.py:
  :: 

    from pygments.style import Style
    from pygments.token import Keyword, Name, Comment, String, Error, Number, Operator, Generic

    class lsiClass(Style):
        default_style = "sphinx"
        styles = {
            Comment:                'bold #800',
            Keyword:                'bold #005',
            Name:                   '#f00',
            Name.Function:          '#0f0',
            Name.Class:             'bold #0f0',
            String:                 'bg:#eee #111'
        }

For details, see the `Pygments Docu <http://pygments.org/docs/styles/>`_
103

Holger Dinkel's avatar
Holger Dinkel committed
104 105 106 107 108 109 110 111 112

Option lists
^^^^^^^^^^^^
For formatting Option Lists see the following docu:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists
-a         Output all.
-b         Output both (this description is quite long).
-c arg     Output just arg.
--long     Output all day long.