← 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-02-23 23:47:02 UTC
  • mfrom: (1099.1.211 new-dispatch)
  • Revision ID: grantw@unimelb.edu.au-20090223234702-db4b1llly46ignwo
Merge from lp:~ivle-dev/ivle/new-dispatch.

Pretty much everything changes. Reread the setup docs. Backup your databases.
Every file is now in a different installed location, the configuration system
is rewritten, the dispatch system is rewritten, URLs are different, the
database is different, worksheets and exercises are no longer on the
filesystem, we use a templating engine, jail service protocols are rewritten,
we don't repeat ourselves, we have authorization rewritten, phpBB is gone,
and probably lots of other things that I cannot remember.

This is certainly the biggest commit I have ever made, and hopefully
the largest I ever will.

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