1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
.. IVLE - Informatics Virtual Learning Environment
Copyright (C) 2007-2009 The University of Melbourne
.. This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.. This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
.. You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
********************
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: http://sphinx.pocoo.org/
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
===============
.. _semantic markup: http://sphinx.pocoo.org/markup/inline.html
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.
|