Sphinx - Githubissues

Guys, I got sphinx working. A bit rough at the moment, but a basic framework is there (see doc/_build/html/index.html on my fork). The short of it is that all of the sphinx files are being tracked, so the only additional steps you have to take to get it working are install sphinx and numpydoc, and set up a git hook (git hooks are not tracked; see below).

I mostly followed this example: https://erget.wordpress.com/2014/05/31/autodocumentation-with-sphinx-and-git-hooks/

To get numpydoc to work (which just adds some additional formatting to numpy-style docstrings), after $conda install numpydoc, added numpydoc to the Sphinx extensions in conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'numpydoc',
]

there's a lot more we can do to improve the formatting and layout of the documentation. For example, the autosummary extension allows methods to be listed with only a brief description, with a link to a full description. I tried implementing this for the Res class, and got the list with the links, but the methods are still all listed below instead of on their own pages.

finally, I set up a git hook so that documentation is rebuilt every time I commit. This may be too frequent. There are other git hooks that we could use instead. https://www.atlassian.com/git/tutorials/git-hooks/conceptual-overview http://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

to install the hook, I made this file: .git/hooks/post-commit, which contains:

#!/bin/sh

cd doc
make html

(I think make html will work on Windows too, but haven't tested it). On mac there is the additional step of making it executable by running $chmod -x .git/hooks/post-commit from the main folder of the repository.

Right now with our private repo, it seems like we can only view the documentation pages locally, but whenever we convert the repo to public, we can generate GitHub pages as described in the example.

PESTools / pestools

Sphinx #20