Docs Docs Docs!

[shaharkadmiel]

Hi all,

It is no secret that the docs for this package are non existent. In order for people to start using this package it needs documentation and I need your help to get that done.

For starters, say I adopt the

:type x: int
:param x: Bla bla bla

docstring style and go through the package and meticulously document everything, how do I generate the HTML documentations for all modules and functions?

Thanks for your help.

Shahar

[megies]

For a start, it might be enough to have some static tutorial-like docs pages. I think that would be fastest to write, super-easy to maintain and build, and already brings good value for little effort.

Compare e.g. https://github.com/krischer/jane/tree/master/docs and http://krischer.github.io/jane//index.html, using mkdocs.

Creating full-fledged API docs like we do in ObsPy has quite some setup and maintenance overhead with sphinx. It is still a good idea to put API docstring documentation like you mentioned into the source code, that can already be used e.g. in IPython to get help even without an API docs build.

[shaharkadmiel]

Thanks @megies. mkdocs does look like a more than reasonable solution.