Contents
Sphinx is a useful tool for generating documentation from rst-files and docstrings in your python and C/C++ files. The complete documentation of Sphinx can be found on http://sphinx.pocoo.org/
This project contains also a theme named nexiles_theme where the look and feel of nexiles is implemented.
There are two ways to install Sphinx:
you can either use
easy_install Sphinx
or you can include it to your buildout by adding
[buildout]
parts += sphinxbuilder
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepy
Once installed, you can use sphinx-quickstart to generate the hierarchical document structure. It is important that you enable the autodoc-function if asked, so that the module's and classe's docstrings will be included automatically.
The two files index.rst and conf.py, which are located in the doc-folder, contain the main configuration.
For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on `sys.path` -- adapt your `sys.path` in the configuration file accordingly, e.g. export PYTHONPATH=$PYTHONPATH:~/develop/nexiles/NxSphinx
sphinxtest documentation master file, created by
sphinx-quickstart on Mon May 23 16:19:39 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to sphinxtest's documentation!
======================================
Contents:
.. toctree::
:maxdepth: 2
intro
misc/tutorial
.. automodule:: useful_1
:members:
.. automodule:: useful_2
:members:
:undoc-members:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
The TOC tree specifies the table of contents shown in the documentation:
toctree
'maxdepth', 'titlesonly' and 'numbered' can be used to format the toc tree. See also http://sphinx.pocoo.org/markup/toctree.html#toctree-directive
The following docstring directives are the most important ones, for a full list see http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc
automodule autoclass autofunction autoattribute autoexception
documents a module, class, function, attribute or exception. The 'members' shown in the example option will document all module members recursively. Members without docstring will be left out, unless a 'undoc-members' option is given.
'intro' and 'misc/tutorial' are documents in rst format that will be included in the documentation having the folder that includes the 'conf.py' as root.
This file is automatically generated by the sphinx-quickbuilder and contains parameters like paths, folder names, activated extension and so on. The parameters are described each in the file itself and at http://sphinx.pocoo.org/config.html
Note
please be sure to add/edit lines below in your conf.py
pip install sphinx_bootstrap_theme
import sys, os, sphinx_bootstrap_theme
templates_path = ['_templates',os.path.expanduser("~/develop/nexiles/NxSphinx/templates")]
html_static_path = ['_static',os.path.expanduser("~/develop/nexiles/NxSphinx/static")]
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme = 'nexiles_green'
html_theme_path = ['_themes',os.path.expanduser("~/develop/nexiles/NxSphinx/themes")]
html_theme = 'nexiles_petrol'
html_theme_path = ['_themes',os.path.expanduser("~/develop/nexiles/NxSphinx/themes")]
html_logo = './nexiles_logo_white.png'
html_theme = 'nexiles_theme'
html_theme_path = ['_themes',os.path.expanduser("~/develop/nexiles/NxSphinx/doc")]
epub_title = u'Developer Documentation'
epub_author = u'nexiles GmbH'
epub_publisher = u'nexiles GmbH'
epub_copyright = u'2013, nexiles GmbH'
epub_theme = 'nexiles_epub_theme'
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
'_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
'_static/basic.css', 'search.html', '_static/websupport.js']
epub_cover = ("_static/cover.png", "epub-cover.html")
epub_tocdepth = 1
epub_tocdup = False
Epub publishing with fixed fonts is not by default supported on ipad. To solve this, you have to link the META-INF directory into your docs-folder.
cd docs ln -s ~/develop/nexiles/NxSphinx/META-INF META-INF
and after every make epub you will have to add the file from the META-INF folder
zip -r0 _build/epub/NAMEOFYOURFILE.epub META-INF
To use your own cover create a directory in docs named _static and save your cover as cover.png there.
See also http://sphinx.pocoo.org/markup/para.html
note - used to show important information
.. note::
It is not recommended to use this function in conjunction with :func:´foo´.
warning - used to show more important information
.. warning::
This function is not failsafe and may corrupt your database.
rubric - creates a paragraph heading without toc-entry
.. rubric:: VERY USEFUL TITLE
centered - creates a centered boldfaced line of text.
.. centered:: LICENSE AGREEMENT
hlist - creates a compact list displayed horizontally or with reduced spacing between items.
.. hlist::
:columns: 3
* this
* is a
* short
* list
seealso - creates a reference to modules or external documents
.. seealso::
Module :py:mod:`zipfile`
Documentation of the :py:mod:`zipfile` standard module.
code-block - creates a block of code
.. code-block:: python
# This is some python code
a = 1
b = 2
print a + b
Interactive sessions don't need special markup, just avoid >>> at end of the block
>>> 1 + 2 3
Longer code blocks can be included using
.. literalinclude:: example.py
:language: python
:encoding: latin-1
:pyobject: Timer.start
:lines: 1,3,5-10,20-
See also http://sphinx.pocoo.org/markup/code.html for code specific markup.