Writing documentation for IdeaLoom

The documentation of IdeaLoom’s backend is written using Sphinx. Writing python documentation requires being familiar with Restructured Text and the Sphinx python domain, especially how to make python cross-references .

The existing Frontend documentation should follows the JSDoc3 standard, but does so loosely at this point. We are connecting it with Javascript using jsdoc_rst_template. It should be possible to cross-reference python and javascript using the Sphinx javascript domain. Examples forthcoming.

You can build it with fab -c assembl/configs/develop.rc build_doc, and the HTML result can subsequently be found in assembl/static/techdocs.

Cheat sheet

How to insert hyperlinks to various objects:

:doc:`name_of_rst_document_without_extension` (relative link)

`Text of hyperlink <http://url_of_hyperlink>`_

`Name of hyperlink`_

.. _`Name of hyperlink`: http://location.of.hyperlink.com/

``inline literal``

:js:class:`JsClassNameWithoutNamespace`

:py:mod:`dotted.module.or.package`

:py:class:`dotted.class`

:py:meth:`dotted.class.method`

:py:func:`dotted.function`

:py:data:`dotted.module.variable`

:py:const:`dotted.constant`

:py:attr:`dotted.instance.or.class.variable`

:py:exc:`dotted.exception`

:py:obj:`dotted.instance`