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 mailing list or you can submit a patch directly against the source.
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.
For basic reStructured Text operations, we are using Sphinx version 1.3.6:
You will need the gitpython python package for performing datestamp operations:
You will also need the perl package, which is used to build some docs from their Perl source:
For editing and preview
- Has a full feature set
- Minimal syntax highlighting for .rst files.
- or any text editor
- No preview capability
- Some editors have syntax highlighting support for .rst files.
For interaction with the repositories
Building the files¶
The best way to build the documentation is to use the toplevel Makefile (generated as part of building the source):
make doc-html doc-text man and places the relevant output in
If you don’t have a full source build environment and just want to manage the documentation on its own, from the docsrc/` directory run:
make clean init man html
This generates the manpages and the html files. The results are in
make with no arguments for a list of available output targets.
Using GitHub pull requests¶
We operate on the GitHub fork/pull model. We’d love to have your pull request come through!
If you’re new to GitHub or the fork/pull model, we have a Quick GitHub guide to get you going.
Conventions: Man Pages¶
For Unix manual, or “man” pages, we follow the conventions laid out in the man page for man(1) itself:
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.
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.
In reStructured Text, this means a SYNOPSIS section might look like this:
Synopsis ======== **ipurge** [ **-f** ] [ **-C** *config-file* ] [ **-x** ] [ **-X** ] [ **-i** ] [ **-s** ] [ **-o** ] [ **-d** *days* | **-b** *bytes* | **-k** *Kbytes* | **-m** *Mbytes* ] [ *mailbox-pattern*... ]
Rendering output like this:
ipurge [ -f ] [ -C config-file ] [ -x ] [ -X ] [ -i ] [ -s ] [ -o ] [ -d days | -b bytes | -k Kbytes | -m Mbytes ] [ mailbox-pattern... ]
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.
For example, this is good, and follows the style of the man(8) manpage:
Examples ======== **arbitron -o** .. Old format (no subscribers) short list. .. only:: html tech.Commits 0 tech.Commits.archive 0 **arbitron -d** *14* .. Normal short list format for the past *14* days. .. only:: html tech.Commits 0 2 tech.Commits.archive 0 4
The output would render like so in a manpage:
tech.Commits 0 tech.Commits.archive 0
tech.Commits 0 2 tech.Commits.archive 0 4