From 9a899dcad35335104ba3faf112f954874f13ac3b Mon Sep 17 00:00:00 2001
From: kotfu <kotfu@kotfu.net>
Date: Wed, 15 Jan 2020 22:35:40 -0700
Subject: Clarify how to document instance attributes

---
 docs/doc_conventions.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
index 082235da..e577fd50 100644
--- a/docs/doc_conventions.rst
+++ b/docs/doc_conventions.rst
@@ -140,6 +140,20 @@ and
 See :ref:`custom title<features/argument_processing:Help Messages>`
 
 
+API Documentation
+-----------------
+
+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.
+
+
 Links to API Reference
 ----------------------
 
-- 
cgit v1.2.1