Merge branch 'master' into auto_completer_refactor

1 files changed, 128 insertions, 0 deletions

diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
new file mode 100644
index 00000000..39302fc6
--- /dev/null
+++ b/docs/doc_conventions.rst
@@ -0,0 +1,128 @@
+Documentation Conventions
+=========================
+
+Guiding Principles
+------------------
+
+Follow the `Documentation Principles
+<http://www.writethedocs.org/guide/writing/docs-principles/>`_ described by
+`Write The Docs <http://www.writethedocs.org>`_
+
+In addition:
+
+- We have gone to great lengths to retain compatibility with the standard
+  library cmd, the documentation should make it easy for developers to
+  understand how to move from cmd to cmd2, and what benefits that will provide
+- We should provide both descriptive and reference documentation.
+- API reference documentation should be generated from docstrings in the code
+- Documentation should include rich hyperlinking to other areas of the
+  documentation, and to the API reference
+
+
+Naming Files
+------------
+
+- all lower case file names
+- if the name has multiple words, separate them with an underscore
+- all documentation file names end in '.rst'
+
+
+Heirarchy of headings
+---------------------
+
+show the heirarchy of sphinx headings we use, and the conventions (underline
+only, no overline)
+
+Use '=', then '-', then '~'. If your document needs more levels than that,
+break it into separate documents.
+
+You only have to worry about the heirarchy of headings within a single file.
+Sphinx handles the intra-file heirarchy magically on it's own.
+
+Use two blank lines before every heading unless it's the first heading in the
+file. Use one blank line after every heading
+
+
+Code
+----
+
+This documentation declares python as the default Sphinx domain.  Python code
+or interactive python sessions can be presented by either:
+
+- finishing the preceding paragraph with a ``::`` and indenting the code
+- use the ``.. code-block::`` directive
+
+If you want to show other code, like shell commands, then use ``.. code-block:
+shell``.
+
+
+Table of Contents and Captions
+------------------------------
+
+
+Hyperlinks
+----------
+
+If you want to use an external hyperlink target, define the target at the top
+of the page, not the bottom.
+
+
+We use the Sphinx `autosectionlabel
+<http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`_
+extension. This allows you to reference any header in any document by::
+
+   See :ref:`features/argument_processing:Help Messages`
+
+or ::
+
+   See :ref:`custom title<features/argument_processing:Help Messages>`
+
+Which render like
+
+See :ref:`features/argument_processing:Help Messages`
+
+and
+
+See :ref:`custom title<features/argument_processing:Help Messages>`
+
+[TODO what's the right way to link to source code? Can we make it link to the
+tag that the documentation is rendered from?]
+
+
+Autolinking
+-----------
+
+
+Referencing cmd2 API documentation
+----------------------------------
+
+
+Info and Warning Callouts
+-------------------------
+
+
+Wrapping
+--------
+
+Hard wrap all text with line lengths no greater than 79 characters. It makes
+everything easier when editing documentation, and has no impact on reading
+documentation because we render to html.
+
+
+Referencing cmd2
+-----------------
+
+Whenever you reference ``cmd2`` in the documentation, enclose it in double
+backticks. This indicates an inline literal in restructured text, and makes it
+stand out when rendered as html.
+
+Style Checker
+-------------
+
+Use `doc8 <https://pypi.org/project/doc8/>`_ to check the style of the
+documentation. This tool can be invoked using the proper options by typing:
+
+.. code-block:: shell
+
+   $ invoke doc8
+