geophysics/MTpy — pull request #14 by nietky (2012-10-10 10:24:56+00:00)
Title: Sphinx docs

This is a PR to address #9

--

The documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html) source files at ``doc/*.rst`` and built into HTML using [Sphinx](http://sphinx.pocoo.org/).

The HTML files are then copied to the orphan ``gh-pages`` branch of this repo, and that branch is served as a static site at http://geophysics.github.com/MTpy. The theme is set by ``html_theme`` on [line 94](https://github.com/geophysics/MTpy/blob/sphinx-docs/doc/conf.py#L94) of ``conf.py``. There are eight [built-in themes](http://sphinx.pocoo.org/theming.html#builtin-themes) to choose from.

--

At the moment the Sphinx build-and-deploy script is only working for me because I have another local repo clone of just the gh-pages branch, but I'll try to write something so anyone can build it.

If you want to build the docs locally it's just:

$ cd doc
$ make html

and the build is then in ``/doc/.build/html``.

--

At the moment the only RST files are short ones for each module, although I've left out MTPlotTools until someone fixes the duplicate versions (#5). They have [automodule](http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc) directives which pull in the docstrings from the source. These look a bit ugly at the moment. There is a bit of a trick to formatting them. You can either use the Sphinx-specific [info field list format](http://sphinx.pocoo.org/domains.html?highlight=param#info-field-lists) although this looks really bad in the source itself, so I don't think it's a good idea. I prefer a style like this for a docstring:

Summary of the function.

Args:
- *first_arg*: string, name of something
- *another*: int, optional

Kwargs:
- *func*: function, called by blah, it's a really complicated argument
and so the description needs to spill over onto two lines.
- *dtype*: numpy dtype

Returns: tuple *(indices, list)*

- *indices*: list of numbers
- *list*: some list of objects

Such a complicated function, more text blah blah blah.

That renders OK in HTML, and looks good in text and tooltips as well.