1
.. IVLE - Informatics Virtual Learning Environment
2
Copyright (C) 2007-2009 The University of Melbourne
4
.. This program is free software; you can redistribute it and/or modify
5
it under the terms of the GNU General Public License as published by
6
the Free Software Foundation; either version 2 of the License, or
7
(at your option) any later version.
9
.. This program is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
GNU General Public License for more details.
14
.. You should have received a copy of the GNU General Public License
15
along with this program; if not, write to the Free Software
16
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22
The IVLE docs are written entirely in `Sphinx`_, with the exception of user
23
docs. Documentation is divided into three sections, by target audience:
25
* User documentation is currently maintained as raw HTML files in individual
26
files within the source tree. For example, the "Browser" help page is
27
located at ``/ivle/webapp/filesystem/browser/help.html``. These files do not
28
have an HTML header; their outer element should be ``<div
30
* Advanced users and system administrators documentation, called "The IVLE
31
Manual", located within the source tree at ``/doc/man``. This section should
32
not describe any of the code or system architecture, except as visible to
33
the system administrator.
34
* Developer documentation, located within the source tree at ``/doc/dev``.
35
This should describe the architecture and workings of the system, but not
36
document specific functions (that should be done as docstrings in the Python
39
.. _Sphinx: http://sphinx.pocoo.org/
41
Sphinx documentation style
42
==========================
47
reStructuredText allows arbitrary heading styles. Use the following heading
66
As much as possible, use `semantic markup`_. For example, when describing a
67
command-line option, use ``:option:`optname``` rather than ````optname````.
68
This is more semantic, prettier, and generates links where possible.
73
External links should be written in the form ```http://example.com`_`` or
74
```Example <http://example.com>`_``. Better yet, use the name only in quotes,
75
such as ```Example`_``, and at the end of the section, include the reference,
78
.. _Example: http://example.com
80
Internal links *should* be written in the form ``:ref:`ref-section-name```.
81
Note that the form ```ref-section-name`_`` is also valid, but has some
82
significant drawbacks:
84
* It doesn't work across files,
85
* On a broken link, it will just link to a page called ``ref-section-name``,
86
rather than producing a Sphinx compile-time error.
88
Therefore, **always** use the ``:ref:`` notation for internal links.
90
When cross-referencing a section label, place the label above the section
91
heading, with one blank line in between the label and heading, like this::
98
.. _semantic markup: http://sphinx.pocoo.org/markup/inline.html
100
Publishing documentation to the website
101
=======================================
103
We currently publish documentation to our old Google Code Subversion
104
repository, so they can be linked to from the website. This is done with the
105
``ivle-push-docs-to-gc`` script in ``lp:~ivle-dev/ivle/dev-scripts``. See
106
the comments at the top of that file for instructions.
added
removed
doc/dev/docs.rst
