Write details for two sections

- titles and headings
- referencing methods

1 files changed, 104 insertions, 15 deletions

diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
index 39302fc6..226c5edc 100644
--- a/docs/doc_conventions.rst
+++ b/docs/doc_conventions.rst
@@ -22,25 +22,60 @@ In addition:
 Naming Files
 ------------
 
-- all lower case file names
+All source files in the documentation must:
+
+- have all lower case file names
 - if the name has multiple words, separate them with an underscore
-- all documentation file names end in '.rst'
+- end in '.rst'
+
+
+Titles and Headings
+-------------------
+
+reStructuredText allows flexibility in how headings are defined. You only have
+to worry about the heirarchy of headings within a single file. Sphinx magically
+handles the intra-file heirarchy on it's own. This magic means that no matter
+how you style titles and headings in the various files that comprise the
+documentation, Sphinx will render properly structured output. To ensure we have
+a similar consistency when viewing the source files, we use the following
+conventions for titles and headings:
+
+1. When creating a heading for a section, do not use the overline and underline
+syntax. Use the underline syntax only::
+
+  Document Title
+  ==============
+
+2. The string of adornment characters on the line following the heading should
+be the same length as the title.
+
+3. The title of a document should use the '=' adornment character on the next
+line and only one heading of this level should appear in each file.
+
+4. Sections within a document should have their titles adorned with the '-'
+character::
+
+  Section Title
+  -------------
 
+5. Subsections within a section should have their titles adorned with the '~'
+character::
 
-Heirarchy of headings
----------------------
+  Subsection Title
+  ~~~~~~~~~~~~~~~~
 
-show the heirarchy of sphinx headings we use, and the conventions (underline
-only, no overline)
+6. Use two blank lines before every title unless it's the first heading in the
+file. Use one blank line after every heading.
 
-Use '=', then '-', then '~'. If your document needs more levels than that,
-break it into separate documents.
+7. If your document needs more than three levels of sections, 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
+Indenting
+---------
+
+In reStructuredText all indenting is significant. Use 2 spaces per indenting
+level.
 
 
 Code
@@ -85,9 +120,6 @@ 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
 -----------
@@ -96,6 +128,63 @@ Autolinking
 Referencing cmd2 API documentation
 ----------------------------------
 
+[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?]
+
+It's easy to reference and create a link to the API documentation for classes,
+methods, functions, or attributes.
+
+
+Referencing Methods
+~~~~~~~~~~~~~~~~~~~
+
+To reference a method, use one of the following approaches:
+
+1. Reference the full dotted path of the method::
+
+     The :meth:`cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in
+     print function.
+
+Which renders as: The :meth:`cmd2.cmd2.Cmd.poutput` method is similar to the
+Python built-in print function.
+
+2. Reference the full dotted path to the method, but only display the method
+name::
+
+     The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in print function.
+
+Which renders as: The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the
+Python built-in print function.
+
+3. Reference a portion of the dotted path of the method::
+
+     The :meth:`.cmd2.Cmd.poutput` method is similar to the Python built-in print
+     function.
+
+Which renders as: The :meth:`.cmd2.Cmd.poutput` method is similar to the Python
+built-in print function.
+
+Avoid either of these approaches:
+
+1. Reference just the class name without enough dotted path::
+
+     The :meth:`.Cmd.poutput` method is similar to the Python built-in print
+     function.
+
+Because ``cmd2.Cmd`` subclasses ``cmd.Cmd`` from the standard library, this
+approach does not clarify which class it is referring to.
+
+2. Reference just a method name::
+
+     The :meth:`poutput` method is similar to the Python built-in print
+     function.
+
+While Sphinx may be smart enough to generate the correct output, the potential
+for multiple matching references is high, which causes Sphinx to generate
+warnings. The build pipeline that renders the documentation treats warnings as
+fatal errors. It's best to just be specific about what you are referencing.
+
+
 
 Info and Warning Callouts
 -------------------------