← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/dev/docs.rst

  • Committer: William Grant
  • Date: 2009-01-13 01:36:15 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:1123
Merge setup-refactor branch. This completely breaks existing installations;
every path (both filesystem and Python) has changed. Do not upgrade without
knowing what you are doing.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev/docs.rst
1
 
.. IVLE - Informatics Virtual Learning Environment
2
 
   Copyright (C) 2007-2009 The University of Melbourne
3
 
 
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.
8
 
 
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.
13
 
 
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
17
 
 
18
 
********************
19
 
Documentation Policy
20
 
********************
21
 
 
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:
24
 
 
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
29
 
  class="helpfile">``.
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
37
 
  code).
38
 
 
39
 
.. _Sphinx: http://sphinx.pocoo.org/
40
 
 
41
 
Sphinx documentation style
42
 
==========================
43
 
 
44
 
Headings
45
 
--------
46
 
 
47
 
reStructuredText allows arbitrary heading styles. Use the following heading
48
 
styles::
49
 
 
50
 
 *********
51
 
 Heading 1
52
 
 *********
53
 
 
54
 
 Heading 2
55
 
 =========
56
 
 
57
 
 Heading 3
58
 
 ---------
59
 
 
60
 
 Heading 4
61
 
 ~~~~~~~~~
62
 
 
63
 
Cross-referencing
64
 
-----------------
65
 
 
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.
69
 
 
70
 
Links
71
 
-----
72
 
 
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,
76
 
like this::
77
 
 
78
 
 .. _Example: http://example.com
79
 
 
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:
83
 
 
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.
87
 
 
88
 
Therefore, **always** use the ``:ref:`` notation for internal links.
89
 
 
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::
92
 
 
93
 
 .. _section-name:
94
 
 
95
 
 Section Heading
96
 
 ===============
97
 
 
98
 
.. _semantic markup: http://sphinx.pocoo.org/markup/inline.html
99
 
 
100
 
Publishing documentation to the website
101
 
=======================================
102
 
 
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.