← 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: Matt Giuca
  • Date: 2009-02-24 02:02:03 UTC
  • mto: This revision was merged to the branch mainline in revision 1119.
  • Revision ID: matt.giuca@gmail.com-20090224020203-aqdcjnsj6y7wl32o
Added a new look to the IVLE header bar. Mmmm... Web 2.0.
Added top-level directory image-source, containing SVG and script files for
    generating the images.
ivle/webapp/coremedia/images: Added 'chrome' directory containing the rendered
    images.
Modified ivle/webapp/base/ivle-headings.html and
    ivle/webapp/coremedia/ivle.css to support the new images.
    Note that the H1 and H2 at the top of the page are no longer displayed
    (and their custom styles have been removed). There is a heading image
    instead.

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