Documentation Standards¶

Options / Arguments¶

How do I specify a list of options and their purpose?

Option List¶

The easiest method is to use a reST Option List. Currently, the rendering wastes lots of space, but that can be improved later.

-s: operate silently, not showing progress during the download
-b FILE: store the HTTP Cookie in the file system path specified by FILE
-L: enables cURL to follow download location changes controlled by HTTP 3xx redirect response codes
-O: use the same name for the saved file as the remote file name
-f: fail silently, don’t show output on download failure

CSV Table¶

A reST CSV Table is the most concise and gives good results:

-s	operate silently, not showing progress during the download
-b FILE	store the HTTP Cookie in the file system path specified by FILE
-L	enables cURL to follow download location changes controlled by HTTP 3xx redirect response codes
-O	use the same name for the saved file as the remote file name
-f	fail silently, don’t show output on download failure

List Table¶

A reST List Table provides equivalent results but is slightly more verbose. It might be easier to manage than a CSV Table when many columns are involved.

cURL Arguments¶
-s	operate silently, not showing progress during the download
-b FILE	store the HTTP Cookie in the file system path specified by FILE
-L	enables cURL to follow download location changes controlled by HTTP 3xx redirect response codes
-O	use the same name for the saved file as the remote file name
-f	fail silently, don’t show output on download failure

Defintion List¶

reST Defintion Lists are intended more for lengthy definitions as opposed to short list of options. Here’s an example:

-s: operate silently, not showing progress during the download
-b FILE: store the HTTP Cookie in the file system path specified by FILE
-L: enables cURL to follow download location changes controlled by HTTP 3xx redirect response codes
-O: use the same name for the saved file as the remote file name
-f: fail silently, don’t show output on download failure

Tables¶

reST Tables¶

If you need to include a table in documentation, any of the tables used in the Options / Arguments section can be used. Note that if you use a reST table, you can provide a title for the table that will appeared centered above the table. For example:

.. table:: Table 1 (invoice header)
   :widths: auto

   ===== ===============  ======   ==========   =============
   id    invoice_number   amount   cusomer_id   customer_name
   ===== ===============  ======   ==========   =============
   1     1001             500.00   1            Customer 1
   2     1002             240.00   2            Customer 2
   ===== ===============  ======   ==========   =============

produces the following table:

Table 1 (invoice header)¶
id	invoice_number	amount	cusomer_id	customer_name
1	1001	500.00	1	Customer 1
2	1002	240.00	2	Customer 2

If you need a title for your table, or if you need control over column widths, a reST table is probably your best choice.

Markdown Tables¶

Depending upon your needs, a Markdown table may suffice. Syntax for Markdown tables is more concise, involves less typing, and doesn’t require alignment of column contents. For example, the following Markdown:

|id|invoice_number|amount|cusomer_id|customer_name|
|--|--------------|------|----------|-------------|
|1|1001|500.00|1|Customer 1|
|2   |1002 |240.00|2|Customer 2|

produces the following table:

id	invoice_number	amount	cusomer_id	customer_name
1	1001	500.00	1	Customer 1
2	1002	240.00	2	Customer 2

Figures¶

Sometimes you want a title associated with an image. You can do that with a Figure, for example:

.. figure:: assets/alfred_e_neuman.jpg

   Steve Zuar -- Founder

will render in the following manner:

../../_images/standards__alfred_e_neuman.jpg — Steve Zuar – Our Founder¶

Steve is widely recognized as one of the most influential entrepreneurs of the 21st century.