Project

General

Profile

Suricata ยป

Converting Wiki Documentation to Sphinx

Sphinx Documentation Location

The Sphinx formatted documentation has now been merged into master and can be viewed at http://suricata.readthedocs.io/.

Conversion Process

Conversion is being done on a one to one file basis. That is, each wiki page is being converted into a single .rst document. The basic process is basically:

  1. Open up a wiki page in edit mode.
  2. Cut and paste the wiki source into a .rst file with a suitable name. For example, https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Fast_Pattern_Determination_Explained was put into fast-pattern-explained.rst.
  3. Download the images. To prevent image filename conflicts, place the images for fast-pattern-explained.rst into a directory named fast-pattern-explained.
  4. Reformat the text to reStructuredText (reST).

For a primer on reST formatting see http://sphinx-doc.org/rest.html

Conversion Tool

In the sphinx-docs branch there is a tool called convert.py that helps with the conversion process, but doesn't hand everything.

Example usage of converting https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Pcre_(Perl_Compatible_Regular_Expressions) to pcre.rst:

./convert.py "https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Pcre_(Perl_Compatible_Regular_Expressions)" pcre

This will:
  • Download all the images referenced on the page and store them in the directory pcre.
  • Convert h1. headers.
  • Convert h2. headers.
  • Convert h3. headers.
  • Convert image links.
It does not yet handle:
  • Font conversions (though it might).
  • Sample text (likely won't).
  • Tables (likely never).
  • Lists (likely never).

Conversion Basics

h1. (First Level Heading)

Wiki:

h1. Page Title

reST:

Page Title
==========

h2. (Second Level Heading)

Wiki:

h2. Second Level Heading

reST:

Second Level Heading
--------------------

h3. (Third Level Heading)

Wiki:

h3. Third Level Heading

reST:

Third Level Heading
~~~~~~~~~~~~~~~~~~~

Embedded Images

Wiki:

!some-image.png!

reST:

.. image:: path/to/image.png

Font Styling

Wiki reST
*bold* **bold**
_italic_ *italic*
@monospace@ ``monospace``

Code/Configuration Samples

Wiki:

Here is an example of something:
<pre>
Here is the unformatted example text.
A second line.
</pre>

reST:

Here is an example of something::

  Here is the first line of the example.

  And more lines can follow but must be indented.

Document References

Wiki:

[[Global-Thresholds]]

reST:

:doc:`global-thresholds`

if the global thresholds documentation is in global-thresholds.rst.

Tables

See the reST documentation on tables: http://sphinx-doc.org/rest.html#tables