"Fossies" - the Fresh Open Source Software Archive

Member "drizzle-7.1.36-stable/docs/contributing/documentation.rst" (6 May 2012, 5021 Bytes) of package /linux/misc/old/drizzle-7.1.36-stable.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

Contributing Documentation

Our documentation is written using Sphinx Documentation Generator which uses the reStructuredText format.

All our documentation is stored in the main source reposatory in the docs/ directory, and every merge into trunk triggers a rebuild of our documentation site.

Requirements

We require a minimum of python-sphinx 0.6 to compile the documentation but not all of it will build correctly in that version. For correct documentation version 1.0 is required.

When building the documentation warnings are treated as errors, so the documentation needs to be warning free in 1.0.

Documentation Files

The documentation files have the .rst extension and are stored in the docs/ directory.

Contents

To add a new document to the contents you will need to add it to a relevent section in the docs/index.rst file.

Plugins

To document plugins you need to create a docs/ subdirectory in your plugin directory containing an index.rst file. This will be automatically added during the config/autorun.sh phase.

Documentation Format

The documentation is in the reStructured text format which is a wiki-like markup language ideal for documentation.

Headings

Headings take the form of just the text with a diffent style of underline to signify the level, for example:

Heading Level 1
===============

Heading Level 2
---------------

Heading Level 3
^^^^^^^^^^^^^^^

Tables

There are two ways of generating a table, the first is basically drawing the entire table in ascii art as follows:

+----+--------+-----+
| ID | name   | age |
+====+========+=====+
| 1  | Fred   | 23  |
+----+--------+-----+
| 2  | Joe    | 48  |
+----+--------+-----+
| 3  | Sophie | 32  |
+----+--------+-----+

Which generates:

ID name age
1 Fred 23
2 Joe 48
3 Sophie 32

As an alternative there is a simplified form as follows:

----- ----- ------
  A     B   Result
===== ===== ======
False False False
False True  True
True  False True
True  True  False
===== ===== =====

Gives this table:

A B Result
False False False
False True True
True False True
True True False

In this form there must be more than one row to the table and the first column can only have a single line.

Syntax Highlighting

Sphinx supports syntax highlighting using the Pygments engine. For example, with the mysql syntax highlighter you can do the following:

.. code-block:: mysql

   SELECT * FROM t1 WHERE a=1;

Which will generate:

SELECT * FROM t1 WHERE a=1;

You can also add line numbers as follows:

.. code-block:: c
   :linenos:

   #include <stdio.h>

   main()
   {
     printf("hello world");
   }

Which will generate:

#include <stdio.h>

main()
{
  printf("hello world");
}

Pygments Demo - A demo of the available syntax highlighting types.

Footnotes

Footnotes in their most simple form can be generated using [1]_ in the text and then a section of the bottom of the page as follows1:

.. rubric:: Footnotes

.. [1] Like this

Which generates:

Footnotes

Notes, Warnings, Todo and See Also

Notes, warnings and todos all take similar forms:

.. note::
   This is a note

.. warning::
   This is a warning

.. todo::
   This is a todo

.. seealso::
   This is a See Also

Which generates:

Note

This is a note

Warning

This is a warning

This is a todo

This is a See Also

Summary

Building Documentation

The documentation is compiled from the .rst files during make, but to create HTML files from this you will need to run make html.

To see other possible formats run make sphinx-help.

Committing Documentation

Documentation needs to be committed and merged in exactly the same way as regular development files. For more information see contributing_code.


  1. Like this↩︎