Documentation Policy

The IVLE docs are written entirely in Sphinx, with the exception of user docs. Documentation is divided into three sections, by target audience:

• User documentation is currently maintained as raw HTML files in individual files within the source tree. For example, the “Browser” help page is located at /ivle/webapp/filesystem/browser/help.html. These files do not have an HTML header; their outer element should be <div class="helpfile">.
• Advanced users and system administrators documentation, called “The IVLE Manual”, located within the source tree at /doc/man. This section should not describe any of the code or system architecture, except as visible to the system administrator.
• Developer documentation, located within the source tree at /doc/dev. This should describe the architecture and workings of the system, but not document specific functions (that should be done as docstrings in the Python code).

Sphinx documentation style

Headings

reStructuredText allows arbitrary heading styles. Use the following heading styles:

*********
Heading 1
*********

Heading 2
=========

Heading 3
---------

Heading 4
~~~~~~~~~

Cross-referencing

As much as possible, use semantic markup. For example, when describing a command-line option, use :option:`optname` rather than ``optname``. This is more semantic, prettier, and generates links where possible.

Links

External links should be written in the form `http://example.com`_ or `Example <http://example.com>`_. Better yet, use the name only in quotes, such as `Example`_, and at the end of the section, include the reference, like this:

.. _Example: http://example.com

Internal links should be written in the form :ref:`ref-section-name`. Note that the form `ref-section-name`_ is also valid, but has some significant drawbacks:

• It doesn’t work across files,
• On a broken link, it will just link to a page called ref-section-name, rather than producing a Sphinx compile-time error.

Therefore, always use the :ref: notation for internal links.

When cross-referencing a section label, place the label above the section heading, with one blank line in between the label and heading, like this:

.. _section-name:

Section Heading
===============

Publishing documentation to the website

We currently publish documentation to our old Google Code Subversion repository, so they can be linked to from the website. This is done with the ivle-push-docs-to-gc script in lp:~ivle-dev/ivle/dev-scripts. See the comments at the top of that file for instructions.