← 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: 2010-02-24 01:21:07 UTC
  • Revision ID: grantw@unimelb.edu.au-20100224012107-e02qr9ce1ftg05y5
Remove unused UserRESTView and associated infrastructure.

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.