Major overhaul of documentation structure for #709

1 files changed, 109 insertions, 0 deletions

diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
new file mode 100644
index 00000000..504c930d
--- /dev/null
+++ b/docs/doc_conventions.rst
@@ -0,0 +1,109 @@
+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>`
+
+
+
+Autolinking
+-----------
+
+
+Referencing cmd2 API documentation
+----------------------------------
+
+
+Info and Warning Callouts
+-------------------------
+
+
+Wrapping
+--------
+
+Hard wrap all text with line lengths less than 80 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.
+