← 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-23 06:11:58 UTC
  • Revision ID: grantw@unimelb.edu.au-20100223061158-05cqg88387ymjtlj
https://launchpad.net/bugs/526228
Redo console CSS, and replace the examples on the help page with something more like the modern console that also doesn't break the real console with ID conflicts.

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.