8.1. Formatting¶
The tesseract manual is written in reStructuredText and processed with Sphinx. This document does not intend to outline how the documentation is generated. Only to provide a style guidelines and samples that are used through the rest of the manual.
There are some general rules to follow:
- Keep all documentation to 80 columns unless it cannot be avoided (for example, long tables or code snippets).
- The documentation here is intended to be easily read and maintained. Do not use fancy features that make the reStructuredText less readable simply to make the result HTML look more pretty.
8.1.1. Basic¶
Always H1 for first level headings and always use an underlined heading rather than hashes:
Heading 1
=========
Heading 2
---------
Heading 3
^^^^^^^^^
Each heading of any strength should have two blank lines above it (unless it is the first line of the file.)
8.1.2. SQL Examples¶
SQL examples should be used in fenced blocks and not include the following semi-colon:
.. code-block:: sql
SELECT foo FROM bar
SELECT foo FROM bar
If you would like to show the result of the SQL it must be in a separate block for JSON:
.. code-block:: json
{"foo": "bar"}
{"foo": "bar"}
8.1.3. Syntax Descriptions¶
When describing SQL syntax use a SQL block:
.. code-block:: sql
SELECT <some_columns>
FROM <table>
SELECT <some_columns>
FROM <table>
For each of the placeholders use a definition style with a blank line between each definition:
some_columns
Lots of nice description here.
table
Even more wonderful information!
- some_columns
- Lots of nice description here.
- table
- Even more wonderful information!
8.1.4. Notes¶
Notes are meant to stand out from other text and contain important information.
.. highlights::
This is important information.
This is important information.
8.1.5. Tables¶
There are two types of table syntax that make the table as small as possible around the text or type to span as much space as possible. Always use the greater span syntax:
.. table::
========= =============
full span syntax
========= =============
for tables
with multiple rows
========= =============
full span | syntax |
---|---|
for | tables |
with | multiple rows |