Writing Documentation

Adding new documentation

If any new documentation files are added the need to be added to the toctree for that section. This is usually found in the index.rst file for the directory you need to add your documentation to. For example in the community/ directory the index.rst file contains a toctree similar to this:

Each one are implied to have a .rst extension. Each file will compile to a seperate HTML file when built with Sphinx.

Adding a module document

In addition to adding to the toctree, modules should be added to the big table in modules/index.rst. This has three columns, the module language should use the :doc: directive to point to a .rst file for the documentation. The description should be a summary of a few words. The repository should use the github or bitbucket directive if possible, or should be a link to the repository if something else was used.

Please keep the modules in alphabetical order, this makes it easier for others to find them.

reStructuredText Basics

These are the basics for writing reStructuredText files. For more imformation we highly recommend looking at Sphinx’s own documentation and Quick reStructuredText. For a more detailed view what is possible, take a look at the reStructuredText specification.

Like Python, blocks of content are typically nested using whitespace indentation. For example:

.. note::

   This is a note!
   It is multi-line!

Note

This is a note! It is multi-line

Inline Markup

There are various inline markups you can use for basic text formatting. For example:

* *emphasis*
* **bold**
* ``literal``
* :sub:`subscript`
* :sup:`superscript`
  • emphasis
  • bold
  • literal
  • subscript
  • superscript

Bullets and Lists

Bullets and ordered lists are very simple.

* bullet points are asterisks

  * and can be nested
  * but need a blank line between parent and children

* and another blank line to continue the parent list
  • bullet points are asterisks
    • and can be nested
    • but need a blank line between parent and children
  • and another blank line to continue the parent list
#. An auto-generated numbered list

   #. It too can be nested

#. And continue with the parent

1. Fixed numbered lists
2. Are also possible
  1. An auto-generated numbered list
    1. It too can be nested
  2. And continue with the parent
  1. Fixed numbered lists
  2. Are also possible

Headings

Headings are signified by using characters on the line below to underline them. Different styles signify level. Headings are automatically used to build the table of contents for the wiki:

Heading
=======

SubHeading
----------

More depth
^^^^^^^^^^

Tables

There are two ways to create tables, Grid Tables and Simple Tables.

Grid Tables use ASCII art to design the table. An example is as follows:

+-----------+----------+----------+
| Column 1  | Column 2 | Column 3 |
| Multiline |          |          |
+===========+==========+==========+
| item 1    | stuff    | nonsense |
+-----------+----------+----------+
| item 2    | horizontal span     |
+-----------+----------+----------+
| item 3    | vertical | is       |
+-----------+ span     | possible |
| item 4    |          | too.     |
+-----------+----------+----------+
Column 1 Multiline Column 2 Column 3
item 1 stuff nonsense
item 2 horizontal span
item 3 vertical span is possible too.
item 4

Simple tables on the other hand are less flexible but are easier to create:

======== ======== ========
Column 1 Column 2 Column 3
======== ======== ========
item a   item b   item c
item d   item e   item f
======== ======== ========
Column 1 Column 2 Column 3
item a item b item c
item d item e item f

Syntax Highlighting

Sphinx can highlight the syntax of code blocks. For example:

.. code-block:: c

   #include <stdio.h>

   int main(void)
   {
     printf("Hello World!");
     return 0;
   }
#include <stdio.h>

int main(void)
{
  printf("Hello World!");
  return 0;
}

There is also syntax highlighting for NGINX configuration files, here is an example of this with line numbers:

.. code-block:: nginx
   :linenos:

   server {
       listen          80;
       server_name     domain.com *.domain.com;
       return          301 $scheme://www.domain.com$request_uri;
   }

   server {
       listen          80;
       server_name     www.domain.com;

       index           index.html;
       root            /home/domain.com;
   }
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
server {
    listen          80;
    server_name     domain.com *.domain.com;
    return          301 $scheme://www.domain.com$request_uri;
}

server {
    listen          80;
    server_name     www.domain.com;

    index           index.html;
    root            /home/domain.com;
}

See also

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 follows [1]:

.. rubric:: Footnotes

.. [1] Like this

Which generates:

Footnotes

[1]Like this

Notes, Warnings, Todo and See Also

Notes, warnings and todos all take similar forms. The wiki is configured to hide todo whilst rendering:

.. 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

See also

This is a See Also

NGINX Wiki specific roles

A few extra roles have been added to assist with creating documentation for this wiki.

:icon:

The icon role lets you use Font Awesome icons in text. Simply use as described in the Font Awesome documentation but without the fa prefix and the options comma separated. For example:

A globe example: :icon:`globe`

A globe example:

:github:

This creates a GitHub icon with link based on a GitHub path. For example:

:github:`nginxinc/nginx-wiki`

nginxinc/nginx-wiki

:bitbucket:

This creates a Bitbucket icon with link based on a Bitbucket path. For example:

:bitbucket:`nginx-goodies/nginx-sticky-module-ng`

nginx-goodies/nginx-sticky-module-ng