More improvements to documentation

astrofrog · astrofrog · commit 448d13fc8826 · 2016-11-06T16:34:15.000Z
diff --git a/docs/conf.py b/docs/conf.py
@@ -339,3 +339,5 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+
+nitpicky = True
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,4 +1,4 @@
-Documentation for sphinx_automodapi
+Documentation for sphinx-automodapi
 ===================================
 
 The sphinx-automodapi package provides Sphinx directives that help faciliate
@@ -29,16 +29,24 @@ To use this extension, you will need to add the following entries to the
                   'sphinx_automodapi.automodsumm',
                   'sphinx_automodapi.automodapi']
 
+.. TODO: we could make automodsumm be automatically set up when automodapi is set up
+
 You can then add an ``automodapi`` block anywhere that you want to generate
 documentation for a module::
 
     .. automodapi:: mypackage.mymodule
 
-This will add a section with a list of objects (functions, classes, etc.),
-and for objects like classes, a table of attributes/methods will be shown.
+This will add a section with the docstring of the module, followed by a list of
+functions, and by a list of classes. For each function and class, a full API
+page will be generated.
+
+By default, sphinx_automodapi will try and make a diagram showing an
+inheritance graph of all the classes in the module. This requires graphviz to
+be installed. To disable the inheritance diagram, you can do::
+
+    .. automodapi:: mypackage.mymodule
+       :no-inheritance-diagram:
 
-User guide
-----------
+.. TODO: disable inheritance diagram by default!
 
-.. automodapi:: sphinx_automodapi.test
-   :no-inheritance-diagram:
+.. TODO: mention about api directory being excluded

Original file line number	Diff line number	Diff line change
`@@ -339,3 +339,5 @@`
`339`	`339`	`# If true, do not generate a @detailmenu in the "Top" node's menu.`
`340`	`340`	`#`
`341`	`341`	`# texinfo_no_detailmenu = False`
	`342`	`+`
	`343`	`+nitpicky = True`