Debian Codegraph @

doc/html/_sources/imap/developer/documentation.rst.txt

raw
1 .. _contribute-docs:
2
3 =============
4 Documentation
5 =============
6
7 Overview
8 ========
9
10 Our documentation for the website is held under git source control, the same as the source. We'd love to have your contributions, which can be sent to the :ref:`mailing list <feedback-mailing-lists>` or you can submit a patch directly against the source.
11
12 Our helpfile source uses Sphinx_ and `Restructured Text`_.
13
14 While editing the documentation can take place in any text editor, you'll need tools to fetch the source, generate man pages and html for testing.
15
16 Documentation Tools
17 ===================
18
19 For basic reStructured Text operations, we are using Sphinx version 1.3.6:
20
21 * python-sphinx
22 * python-sphinxcontrib-programoutput
23 * python-sphinxcontrib.actdiag
24 * python-sphinxcontrib.blockdiag
25 * python-sphinxcontrib.nwdiag
26 * python-sphinxcontrib.phpdomain
27 * python-sphinxcontrib.seqdiag
28 * python-sphinxcontrib.spelling
29
30 You will need the `gitpython <https://gitpython.readthedocs.io/en/stable/>`_
31 python package for performing datestamp operations:
32
33 * gitpython
34
35 You will also need the perl package, which is used to build some docs from their Perl source:
36
37 * Pod::POM::View::Restructured
38
39 For editing and preview
40
41 * `geany <http://www.geany.org>`_
42 * Has a full feature set
43 * Minimal syntax highlighting for .rst files.
44
45 * `retext <http://sourceforge.net/projects/retext>`_ (`Windows install instructions <http://sourceforge.net/p/retext/wiki/Windows%20Install%20of%20ReText/>`_)
46 * Built-in preview mode.
47 * Struggles with templates
48
49 * or any text editor
50 * No preview capability
51 * Some editors have syntax highlighting support for .rst files.
52
53 For interaction with the repositories
54
55 * git
56 * git-stuff
57
58 Building the files
59 ==================
60
61 The best way to build the documentation is to use the toplevel Makefile (generated as part of
62 :ref:`building the source <compiling>`)::
63
64 make doc
65
66 This runs ``make doc-html doc-text man`` and places the relevant output in ``doc/html/``, ``doc/text/`` and ``man/`` directories.
67
68 If you don't have a full source build environment and just want to manage the documentation
69 on its own, from the `docsrc/`` directory run::
70
71 make clean init man html
72
73 This generates the manpages and the html files. The results are in ``build``.
74
75 Run ``make`` with no arguments for a list of available output targets.
76
77 Submitting updates
78 ==================
79
80 Using GitHub pull requests
81 --------------------------
82
83 We operate on the GitHub fork/pull model. We'd love to have your pull request come through!
84
85 If you're new to GitHub or the fork/pull model, we have a :ref:`Quick GitHub guide <github-guide>` to get you going.
86
87 Patches through the mailing list
88 --------------------------------
89 If you're not planning on regularly submitting changes, you can just send your patch through to the :ref:`mailing list <feedback-mailing-lists>` and one of the regular maintainers will incorporate it.
90
91 .. _Sphinx: http://sphinx-doc.org
92 .. _Restructured Text: http://docutils.sourceforge.net/rst.html
93
94 Special Tags
95 ============
96
97 Our Sphinx setup has a few additional tags that are of note.
98
99 rfc
100 ---
101
102 In HTML output, this generates a link to the referenced document.
103
104 Usage: ``:rfc:`<number>```
105
106 Example: ``:rfc:`3501``` produces :rfc:`3501`.
107
108 cyrusman
109 --------
110
111 In HTML output, this generates an internal link to the referenced man page.
112
113 Currently we support sections 1, 5 and 8. These look for their man pages in the *commands* (1,8) and *config* (5) directories within the source.
114
115 Usage: ``:cyrusman:`<command>(<section>)``` or ``:cyrusman:`<configfile>.conf(5)```
116
117 Example: ``:cyrusman:`imapd.conf(5)``` produces :cyrusman:`imapd.conf(5)`.
118
119 imap_current_stable_version
120 ---------------------------
121
122 This is a replacement tag and will output the current stable version number defined in conf.py.
123
124 Usage: ``|imap_current_stable_version|``
125
126 Produces |imap_current_stable_version|.
127
128 Conventions: Man Pages
129 ======================
130
131 For Unix manual, or "man" pages, we follow the conventions laid out in the man page for man(1) itself:
132
133 .. note::
134
135 Conventional section names include NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, and SEE ALSO. The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.
136
137 | **bold text** - type exactly as shown.
138 | *italic text* - replace with appropriate argument.
139 | [-abc] - any or all arguments within [ ] are optional.
140 | -a|-b - options delimited by | cannot be used together.
141 | argument ... - argument is repeatable.
142 | [expression] ... - entire expression within [ ] is repeatable.
143
144 .. note::
145
146 Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead. The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate several exclusive invocations as is shown in the SYNOPSIS section of this manual page.
147
148 Synopsis
149 --------
150
151 In reStructured Text, this means a SYNOPSIS section might look like this::
152
153 Synopsis
154 ========
155
156 **ipurge** [ **-f** ] [ **-C** *config-file* ] [ **-x** ] [ **-X** ] [ **-i** ] [ **-s** ] [ **-o** ]
157 [ **-d** *days* | **-b** *bytes* | **-k** *Kbytes* | **-m** *Mbytes* ]
158 [ *mailbox-pattern*... ]
159
160 Rendering output like this:
161
162 SYNOPSIS
163
164 **ipurge** [ **-f** ] [ **-C** *config-file* ] [ **-x** ] [ **-X** ] [ **-i** ] [ **-s** ] [ **-o** ] [ **-d** *days* | **-b** *bytes* | **-k** *Kbytes* | **-m** *Mbytes* ] [ *mailbox-pattern*... ]
165
166 Examples
167 --------
168
169 In order to preserve space in traditional man page output, we're using the ``.. only:: html`` directive in the reStructured Text (.rst) files for the verbose output of the Examples for commands.
170
171 For example, this is good, and follows the style of the man(8) manpage::
172
173 Examples
174 ========
175
176 **arbitron -o**
177
178 ..
179
180 Old format (no subscribers) short list.
181
182 .. only:: html
183
184 tech.Commits 0
185 tech.Commits.archive 0
186
187 **arbitron -d** *14*
188
189 ..
190
191 Normal short list format for the past *14* days.
192
193 .. only:: html
194
195 tech.Commits 0 2
196 tech.Commits.archive 0 4
197
198 The output would render like so in a manpage:
199
200 EXAMPLES
201
202 | **arbitron -o**
203 | Old format (no subscribers) short list.
204
205 .. only:: html
206
207 ::
208
209 tech.Commits 0
210 tech.Commits.archive 0
211
212 | **arbitron -d** *14*
213 | Normal short list format for the past *14* days.
214
215 .. only:: html
216
217 ::
218
219 tech.Commits 0 2
220 tech.Commits.archive 0 4