From 03f601ed4171ab658746425f3703c6ad7ce486b4 Mon Sep 17 00:00:00 2001
From: Ashley Whetter <asw@dneg.com>
Date: Fri, 10 Aug 2018 09:01:21 -0700
Subject: [PATCH] Updated documentation

Closes #120
---
 README.rst          | 10 +++++++++-
 docs/config.rst     | 15 ++++++++++++---
 docs/directives.rst | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 4 deletions(-)
 create mode 100644 docs/directives.rst

diff --git a/README.rst b/README.rst
index b1d8d66..74e2cbe 100644
--- a/README.rst
+++ b/README.rst
@@ -41,6 +41,8 @@ Contents
    :maxdepth: 2
 
    design
+   directives
+
 
 Basic Workflow
 --------------
@@ -196,6 +198,12 @@ All of the pages that AutoAPI generates are templated with Jinja2 templates.
 You can fully customize how pages are displayed on a per-object basis.
 Read more about it in :doc:`templates`.
 
+Directives
+----------
+
+Instead of generating API documentation,
+you can write the documentation yourself with :doc:`directives`.
+
 Design
 ------
 
@@ -204,7 +212,7 @@ Read more about the deisgn in our :doc:`design`.
 Currently Implemented
 ---------------------
 
-* Python (2 only -- Epydoc doesn't support Python 3)
+* Python (2.7+ and 3.4+)
 * .NET
 * Go
 * Javascript
diff --git a/docs/config.rst b/docs/config.rst
index b46d651..66958f6 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -25,7 +25,7 @@ Configuration Options
 
 	A directory that has user-defined templates to override our default templates.
 
-        You can see the existing files in the `autoapi/templates`_ directory.
+        You can see the existing files in the `autoapi_templates`_ directory.
 
 .. confval:: autoapi_file_patterns
 
@@ -33,6 +33,15 @@ Configuration Options
 
         A list containing the file patterns to look for when generating documentation. Python for example is ``['*.py']``.
 
+... confval:: autoapi_generate_api_docs
+
+	Default: ``True``
+
+	Whether to generate API documentation.
+	If this is ``False``, documentation should be generated though the
+	:doc:`directives`.
+
+
 Customization Options
 ---------------------
 
@@ -88,7 +97,7 @@ Customization Options
 
 	:param class: Use only the class docstring.
 	:param both: Use the concatentation of the class docstring and the
-	``__init__``/``__new__`` docstring.
+		``__init__``/``__new__`` docstring.
 	:param init: Use only the ``__init__``/``__new__`` docstring.
 
 	If the class does not have an ``__init__`` or the ``__init__``
@@ -105,4 +114,4 @@ Debugging Options
 	Keep the AutoAPI generated files on the filesystem after the run.
 	Useful for debugging.
 
-.. _autoapi/templates:: https://github.com/rtfd/sphinx-autoapi/tree/master/autoapi/templates
+.. _autoapi_templates: https://github.com/rtfd/sphinx-autoapi/tree/master/autoapi/templates
diff --git a/docs/directives.rst b/docs/directives.rst
new file mode 100644
index 0000000..d4e1781
--- /dev/null
+++ b/docs/directives.rst
@@ -0,0 +1,34 @@
+Autodoc-Style Directives
+------------------------
+
+You can opt to write API documentation yourself using autodoc style directives.
+These directives work similarly to autodoc,
+but docstring are retrieved through static analysis instead of through imports.
+
+To use these directives you will need to enable the autodoc extension
+in your Sphinx project's ``conf.py``:
+
+.. code:: python
+
+    extensions = ['sphinx.ext.autodoc', 'autoapi.extension']
+
+
+For Python, all directives have an autodoc equivalent
+and accept the same options.
+The following directives are available:
+
+.. rst:directive:: autoapimodule
+                   autoapiclass
+                   autoapiexception
+
+    Equivalent to :rst:dir:`automodule`, :rst:dir:`autoclass`,
+    and :rst:dir:`autoexception` respectively.
+    :confval:`autodoc_inherit_docstrings` does not currently work.
+
+.. rst:directive:: autoapifunction
+                   autoapidata
+                   autoapimethod
+                   autoapiattribute
+
+    Equivalent to :rst:dir:`autofunction`, :rst:dir:`autodata`,
+    :rst:dir:`automethod`, and :rst:dir:`autoattribute` respectively.