Updating docs for docs

docs/docs.rst

@@ -1,13 +1,13 @@
 .. _docs:
 
-Adding documentation
+Writing documentation
 =====================
 Documentation for |owm| is housed in two locations: 
 
     #. In the top-level project directory as :file:`INSTALL.md` and :file:`README.md`. 
     #. As a `Sphinx <http://sphinx-doc.org/>`_ project under the ``docs`` directory 
 
-By way of example, to add a page about useful facts concerning C. elegans to
+By way of example, to add a page about useful facts concerning *C. elegans* to
 the documentation, include an entry in the list under ``toctree`` in
 :file:`docs/index.rst` like::
 
@@ -22,29 +22,50 @@ to the top of your file, remembering to leave an empty line before adding all
 of your wonderful worm facts.
 
 You can get a preview of what your documentation will look like when it is
-published by running ``sphinx-build`` on the docs directory::
+published by running ``sphinx-build`` on the docs directory. To get the
+``sphinx-build`` command, install the documentation requirements with::
 
-    sphinx-build -w sphinx-errors docs build_destination
+    pip install -r doc-requirements.txt
 
-The docs will be compiled to html which you can view by pointing your web
-browser at :file:`build_destination/index.html`. If you want to view the
-documentation locally with the `ReadTheDocs theme <a_>`_ you'll need to
-download and install it.
+Then, you can run ``sphinx-build`` like this::
+
+    sphinx-build -w sphinx-errors docs <build_destination>
+
+You can also invoke the command with default arguments (i.e., with output to
+:file:`build/sphinx` using :file:`setup.py`::
+
+    python setup.py build_sphinx
 
+The docs will be compiled to html which you can view by pointing your web
+browser at :file:`<build_destination>/index.html`. The documentation will be
+rendered using the same theme as is used on the readthedocs.org site.
 
-.. _a: https://github.com/snide/sphinx_rtd_theme
 
 API Documentation
 -----------------
 API documentation is generated by the Sphinx `autodoc`_ and `apidoc`_
 extensions. The numpydoc format should be easy to pick up on, but a reference
-is available `here <b2_>`_.  Just add a docstring to your function/class/method
-and add an ``automodule`` line to :file:`owmeta_core/__init__.py` and your
-class should appear among the other documented classes.
+is available `here <b2_>`_. Just add a docstring to your function/class/method
+and your class should appear among the other documented classes. Note, however,
+that "special" methods like `__call__` will not show up by default -- if they
+need to be documented for a given class, add a declaration like this to the
+class documentation::
+
+    class SpecialMethodDocExample:
+        '''
+        Example class doc
+
+        .. automethod:: __call__
+        '''
+
+        def __call__(self):
+            '''
+            Hey, I'm in the API documentation!
+            '''
 
 .. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 .. _apidoc: https://github.com/sphinx-contrib/apidoc
-.. _b2: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+.. _b2: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 
 Substitutions
 -------------