-
Notifications
You must be signed in to change notification settings - Fork 1
How to write API documentation
Devilry is documented using the Sphinx documentation generator. You need to learn how to write restructured text and how to use the Sphinx-specific restructured text-directives. All of this is documented on the Sphinx website.
The most relevant Sphinx documentation if you are just documenting a python module is:
- reStructuredText Primer
- Module-specific markup
- Include documentation from docstrings
- [Notes, warnings, seealso ...] (http://sphinx.pocoo.org/markup/para.html)
- Cross-references
- Showing code examples
-
How to cross link Python code. Note that the :py domain is default, so you do not have to prefix with
:py
.
You can find lots of examples in the devilry sourcecode.
docs/core.models.rst
, which documents devilry.apps.core.models, is a good example.
We prefer a howto/examples in addition to API-docs (see docs/grade-plugins.rst
for an example.)
Documentation lives docs/
. Each topic is in a separate file. New files must
be added to both toctree and the overview in index.rst
.
For Python docs: You will need a newer version of Sphinx, at least version 1. Install with:
$ [sudo] easy_install -U Sphinx
For JavaScript docs: You will need the latest version of JSDuck. Install with:
$ [sudo] gem install --pre jsduck
Run:
$ devilryadmin.py docs --openbrowser
to build the Python API docs and open the result in your default browser. Run devilryadmin.py without any arguments to see more docs commands.
Run:
$ devilryadmin.py docs_js --openbrowser
to build the JavaScript API docs and open the result in your default browser.