# 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](
https://docutils.sourceforge.io/docs/user/rst/quickref.html#option-lists
).  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](
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1)
is the most concise and gives good results:

.. csv-table::
   :widths: 5 95

   `-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](
https://docutils.sourceforge.io/docs/ref/rst/directives.html#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.

.. list-table:: `cURL Arguments`
   :widths: 5 95

   * - `-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](
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-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:

```rest
.. 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:: 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
   ===== ===============  ======   ==========   =============


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:

```md
|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:

```rest
.. figure:: assets/alfred_e_neuman.jpg

   Steve Zuar -- Founder
```

will render in the following manner:

.. figure:: assets/standards__alfred_e_neuman.jpg

   Steve Zuar -- Our Founder

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