doc: update doc guidelines

Update the doc writing guidelines to include some new capabilities
(multi-column display, numbered instruction steps) and add more
information about writing tables.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/developer-guides/doc_guidelines.rst

@@ -165,14 +165,13 @@ Would be rendered as:
 Multi-column lists
 ******************
 
-If you have a long bullet list of items, where each item is short,
+If you have a long bullet list of items, where each item is short, you
-you can indicate the list items should be rendered in multiple columns
+can indicate the list items should be rendered in multiple columns with
-with a special ``hlist`` directive:
+a special ``.. rst-class:: rst-columns`` directive.  The directive will
+apply to the next non-comment element (e.g., paragraph), or to content
+indented under the directive. For example, this unordered list::
 
-.. code-block:: rest
+   .. rst-class:: rst-columns
-
-   .. hlist::
-      :columns: 3
 
    * A list of
    * short items
@@ -184,10 +183,9 @@ with a special ``hlist`` directive:
    * space on
    * the page
 
-This would be rendered as:
+would be rendered as:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    * A list of
    * short items
@@ -199,8 +197,88 @@ This would be rendered as:
    * space on
    * the page
 
-Note the optional ``:columns:`` parameter (default is two columns), and
+A maximum of three columns will be displayed, and change based on the
-all the list items are indented by three spaces.
+available width of the display window, reducing to one column on narrow
+(phone) screens if necessary.  We've deprecated use of the ``hlist``
+directive because it misbehaves on smaller screens.
+
+Tables
+******
+
+There are a few ways to create tables, each with their limitations or
+quirks.  `Grid tables
+<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_
+offer the most capability for defining merged rows and columns, but are
+hard to maintain::
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | ...        | ...      | you can  |
+   +------------------------+------------+----------+ easily   +
+   | body row 3 with a two column span   | ...      | span     |
+   +------------------------+------------+----------+ rows     +
+   | body row 4             | ...        | ...      | too      |
+   +------------------------+------------+----------+----------+
+
+This example would render as:
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | ...        | ...      | you can  |
++------------------------+------------+----------+ easily   +
+| body row 3 with a two column span   | ...      | span     |
++------------------------+------------+----------+ rows     +
+| body row 4             | ...        | ...      | too      |
++------------------------+------------+----------+----------+
+
+`List tables
+<http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table>`_
+are much easier to maintain, but don't support row or column spans::
+
+   .. list-table:: Table title
+      :widths: 15 20 40
+      :header-rows: 1
+
+      * - Heading 1
+        - Heading 2
+        - Heading 3
+      * - body row 1, column 1
+        - body row 1, column 2
+        - body row 1, column 3
+      * - body row 2, column 1
+        - body row 2, column 2
+        - body row 2, column 3
+
+This example would render as:
+
+.. list-table:: Table title
+   :widths: 15 20 40
+   :header-rows: 1
+
+   * - Heading 1
+     - Heading 2
+     - Heading 3
+   * - body row 1, column 1
+     - body row 1, column 2
+     - body row 1, column 3
+   * - body row 2, column 1
+     - body row 2, column 2
+     - body row 2, column 3
+
+The ``:widths:`` parameter lets you define relative column widths.  The
+default is equal column widths. If you have a three-column table and you
+want the first column to be half as wide as the other two equal-width
+columns, you can specify ``:widths: 1 2 2``.  If you'd like the browser
+to set the column widths automatically based on the column contents, you
+can use ``:widths: auto``.
 
 File names and Commands
 ***********************
@@ -222,7 +300,7 @@ Don't use items within a single backtick, for example ```word```.
 Internal Cross-Reference Linking
 ********************************
 
-ReST links are only supported within the current file using the
+Traditional ReST links are only supported within the current file using the
 notation:
 
 .. code-block:: rest
@@ -251,7 +329,7 @@ Note the leading underscore indicating an inbound link.
 The content immediately following
 this label is the target for a ``:ref:`my label name```
 reference from anywhere within the documentation set.
-The label should be added immediately before a heading so there's a
+The label **must** be added immediately before a heading so there's a
 natural phrase to show when referencing this label (e.g., the heading
 text).
 
@@ -369,6 +447,30 @@ highlighting package makes a best guess at the type of content in the
 block and highlighting purposes.  This can lead to some odd
 highlighting in the generated output.
 
+Images
+******
+
+Images are included in documentation by using an image directive::
+
+   .. image:: ../../images/doc-gen-flow.png
+      :align: center
+      :alt: alt text for the image
+
+or if you'd like to add an image caption, use::
+
+    .. figure:: ../../images/doc-gen-flow.png
+       :alt: image description
+
+       Caption for the figure
+
+The file name specified is relative to the document source file,
+and we recommend putting images into an ``images`` folder where the document
+source is found.  The usual image formats handled by a web browser are
+supported: JPEG, PNG, GIF, and SVG.  Keep the image size only as large
+as needed, generally at least 500 px wide but no more than 1000 px, and
+no more than 250 KB unless a particularly large image is needed for
+clarity.
+
 Tabs, spaces, and indenting
 ***************************
 
@@ -431,4 +533,44 @@ We've also included the ``graphviz`` Sphinx extension to let you use a text
 description language to render drawings.  See :ref:`graphviz-examples` for more
 information.
 
+Instruction Steps
+*****************
 
+Numbered instruction steps is a style that makes it
+easy to create tutorial guides with clearly identified steps. Add
+the ``.. rst-class:: numbered-step`` directive immediately before a
+second-level heading (by project convention, a heading underlined with
+asterisks ``******``, and it will be displayed as a numbered step,
+sequentially numbered within the document.  (Second-level headings
+without this ``rst-class`` directive will not be numbered.) For example::
+
+   .. rst-class:: numbered-step
+
+   Put your right hand in
+   **********************
+
+.. rst-class:: numbered-step
+
+First instruction step
+**********************
+
+This is the first instruction step material.  You can do the usual paragraphs and
+pictures as you'd use in normal document writing. Write the heading to
+be a summary of what the step is (the step numbering is automated so you
+can move steps around easily if needed).
+
+.. rst-class:: numbered-step
+
+Second instruction step
+***********************
+
+This is the second instruction step.
+
+.. note:: As implemented,
+   only one set of numbered steps is intended per document and the steps
+   must be level 2 headings.
+
+Documentation Generation
+************************
+
+For instructions on building the documentation, see :ref:`acrn_doc`.