Merge pull request #847 from python-cmd2/generating_output_docs

Generating output docs

Author: kmvanbrunt

cmd2/ansi.py

@@ -94,7 +94,9 @@ def strip_style(text: str) -> str:
 def style_aware_wcswidth(text: str) -> int:
     """
     Wrap wcswidth to make it compatible with strings that contains ANSI style sequences
+
     :param text: the string being measured
+    :return: the width of the string when printed to the terminal
     """
     # Strip ANSI style sequences since they cause wcswidth to return -1
     return wcswidth(strip_style(text))
@@ -103,6 +105,7 @@ def style_aware_wcswidth(text: str) -> int:
 def style_aware_write(fileobj: IO, msg: str) -> None:
     """
     Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
+
     :param fileobj: the file object being written to
     :param msg: the string being written
     """
@@ -115,9 +118,10 @@ def style_aware_write(fileobj: IO, msg: str) -> None:
 def fg_lookup(fg_name: str) -> str:
     """
     Look up ANSI escape codes based on foreground color name.
+
     :param fg_name: foreground color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
-    :raises ValueError if the color cannot be found
+    :raises ValueError: if the color cannot be found
     """
     try:
         ansi_escape = FG_COLORS[fg_name.lower()]
@@ -129,9 +133,10 @@ def fg_lookup(fg_name: str) -> str:
 def bg_lookup(bg_name: str) -> str:
     """
     Look up ANSI escape codes based on background color name.
+
     :param bg_name: background color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
-    :raises ValueError if the color cannot be found
+    :raises ValueError: if the color cannot be found
     """
     try:
         ansi_escape = BG_COLORS[bg_name.lower()]
@@ -193,8 +198,13 @@ def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False,
 # These can be altered to suit an application's needs and only need to be a
 # function with the following structure: func(str) -> str
 style_success = functools.partial(style, fg='green')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
+
 style_warning = functools.partial(style, fg='bright_yellow')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
+
 style_error = functools.partial(style, fg='bright_red')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
 
 
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:
@@ -255,6 +265,6 @@ def set_title_str(title: str) -> str:
     """Get the required string, including ANSI escape codes, for setting window title for the terminal.
 
     :param title: new title for the window
-    :return string to write to sys.stderr in order to set the window title to the desired test
+    :return: string to write to sys.stderr in order to set the window title to the desired test
     """
     return colorama.ansi.set_title(title)

cmd2/cmd2.py

@@ -290,7 +290,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         # The error that prints when a non-existent command is run
         self.default_error = "{} is not a recognized command, alias, or macro"
 
-        # If this string is non-empty, then this warning message will print if a broken pipe error occurs while printing
+        # If non-empty, this string will be displayed if a broken pipe error occurs
         self.broken_pipe_warning = ''
 
         # Commands that will run at the beginning of the command loop

docs/api/ansi.rst

@@ -0,0 +1,5 @@
+cmd2.ansi
+=========
+
+.. automodule:: cmd2.ansi
+    :members:

docs/api/cmd.rst

@@ -3,3 +3,20 @@ cmd2.Cmd
 
 .. autoclass:: cmd2.cmd2.Cmd
     :members:
+
+    .. attribute:: help_error
+
+      The error message displayed to the user when they request help for a
+      command with no help defined.
+
+    .. attribute:: default_error
+
+      The error message displayed when a non-existent command is run.
+
+    .. attribute:: settable
+
+        This dictionary contains the name and description of all settings available to users.
+
+        Users use the :ref:`features/builtin_commands:set` command to view and
+        modify settings. Settings are stored in instance attributes with the
+        same name as the setting.

docs/api/index.rst

@@ -7,5 +7,6 @@ API Reference
    cmd
    decorators
    exceptions
+   ansi
    utility_classes
    utility_functions

docs/doc_conventions.rst

@@ -19,61 +19,115 @@ In addition:
   documentation, and to the API reference
 
 
+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
+
+
 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'
 
 
-Heirarchy of headings
----------------------
+Indenting
+---------
 
-show the heirarchy of sphinx headings we use, and the conventions (underline
-only, no overline)
+In reStructuredText all indenting is significant. Use 2 spaces per indenting
+level.
 
-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.
+Wrapping
+--------
 
-Use two blank lines before every heading unless it's the first heading in the
-file. Use one blank line after every heading
+Hard wrap all text so that line lengths are no greater than 79 characters. It
+makes everything easier when editing documentation, and has no impact on
+reading documentation because we render to html.
 
 
-Code
-----
+Titles and Headings
+-------------------
 
-This documentation declares python as the default Sphinx domain.  Python code
-or interactive python sessions can be presented by either:
+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:
 
-- finishing the preceding paragraph with a ``::`` and indenting the code
-- use the ``.. code-block::`` directive
+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::
+
+  Subsection Title
+  ~~~~~~~~~~~~~~~~
 
-If you want to show other code, like shell commands, then use ``.. code-block:
-shell``.
+6. Use two blank lines before every title unless it's the first heading in the
+file. Use one blank line after every heading.
 
+7. If your document needs more than three levels of sections, break it into
+separate documents.
+
+
+Inline 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
 
-Table of Contents and Captions
-------------------------------
+If you want to show non-Python code, like shell commands, then use ``..
+code-block: shell``.
 
 
-Hyperlinks
-----------
+External Hyperlinks
+-------------------
 
 If you want to use an external hyperlink target, define the target at the top
-of the page, not the bottom.
+of the page or the top of the section, not the bottom. The target definition
+should always appear before it is referenced.
 
 
+Links To Other Documentation Pages and Sections
+-----------------------------------------------
+
 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 ::
+or::
 
    See :ref:`custom title<features/argument_processing:Help Messages>`
 
@@ -85,44 +139,80 @@ 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?]
 
+API Documentation
+-----------------
 
-Autolinking
------------
+The API documentation is mostly pulled from docstrings in the source code using
+the Sphinx `autodoc
+<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
+extension. However, Sphinx has issues generating documentation for instance
+attributes (see `cmd2 issue 821
+<https://github.com/python-cmd2/cmd2/issues/821>`_ for the full discussion). We
+have chosen to not use code as the source of instance attribute documentation.
+Instead, it is added manually to the documentation files in ``cmd2/docs/api``.
+See ``cmd2/docs/api/cmd.rst`` to see how to add documentation for an attribute.
 
+For module data members and class attributes, the ``autodoc`` extension allows
+documentation in a comment with special formatting (using a #: to start the
+comment instead of just #), or in a docstring after the definition. This
+project has standardized on the docstring after the definition approach. Do not
+use the specially formatted comment approach.
 
-Referencing cmd2 API documentation
-----------------------------------
 
+Links to API Reference
+----------------------
 
-Info and Warning Callouts
--------------------------
+To reference a method or function, use one of the following approaches:
 
+1. Reference the full dotted path of the method::
 
-Wrapping
---------
+     The :meth:`cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in
+     print function.
 
-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.
+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::
 
-Referencing cmd2
------------------
+     The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in print function.
 
-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.
+Which renders as: The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the
+Python built-in print function.
 
-Style Checker
--------------
+3. Reference a portion of the dotted path of the method::
 
-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:
+     The :meth:`.cmd2.Cmd.poutput` method is similar to the Python built-in print
+     function.
 
-.. code-block:: shell
+Which renders as: The :meth:`.cmd2.Cmd.poutput` method is similar to the Python
+built-in print function.
 
-   $ invoke doc8
+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.
 
+
+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.