Merged in doc-autosummary (pull request #40)

This commit uses the autosummary extension of sphinx to generate a table of the methods for a given class.

Approved-by: Carl Simon Adorf <csadorf@umich.edu>
Approved-by: Vyas Ramasubramani <vramasub@umich.edu>

.gitignore

@@ -27,6 +27,7 @@ pip-log.txt
 .coverage
 .tox
 nosetests.xml
+.pytest_cache
 
 # Translations
 *.mo

changelog.txt

@@ -378,9 +378,7 @@ Removed
 +++++++
 
  - All modules related to the stale *conversion framework* feature have been removed resulting in a removal of the optional networkx dependency.
- - Multiple modules related to the *conversion framework* feature have been
- removed, including: ``contrib.formats_network``, ``contrib.conversion``, and
- ``contrib.adapters``.
+ - Multiple modules related to the *conversion framework* feature have been removed, including: ``contrib.formats_network``, ``contrib.conversion``, and ``contrib.adapters``.
 
 Fixed
 +++++

doc/conf.py

@@ -52,6 +52,7 @@ def __getattr__(cls, name):
     'sphinx.ext.mathjax',
     'nbsphinx',
     'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx.ext.autosummary',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/projects.rst

@@ -7,6 +7,9 @@ Projects
 Introduction
 ============
 
+For a full reference of the Project API, please see the :ref:`Python API
+<python-api-project>`.
+
 A **signac** project is a conceptual entity consisting of three components:
 
   1. a **data space**,
@@ -81,6 +84,9 @@ Or with the :py:func:`~signac.get_project` function:
 Jobs
 ====
 
+For a full reference of the Job API, please see the :ref:`Python API
+<python-api-job>`.
+
 The central assumption of the **signac** data model is that the *data space* is divisible into individual data points, consisting of data and metadata, which are uniquely addressable in some manner.
 In the context of **signac**, each data point is called a *job*, and its unique address is referred to as a *state point*.
 A job can consist of any type of data, ranging from a single value to multiple terabytes of simulation data; **signac**'s only requirement is that this data can be encoded in a file.

doc/query.rst

@@ -112,7 +112,7 @@ The behavior of ``$near`` matches that of python's `math.isclose <https://docs.p
 The "reference" value and tolerances are passed in as a list in the order ``[reference, [relative_tolerance, [absolute_tolerance]]]``, where the inner ``[]``\s denote optional values.
 Note that default values are ``relative_tolerance = 1e-09`` and ``absolute_tolerance = 0``.
 
-.. code-block:: python
+.. code-block:: bash
 
     signac find theta.\$near 0.6  # easier than typing 0.600000001
     signac find '{"p.$near": [100, 0.05]}'  # p within 5% of 100
@@ -221,7 +221,7 @@ Finally, you can use ``/<regex>/`` intead of ``{'$regex': '<regex>'}`` for regul
 
 The following list shows simplified expressions on the left and their equivalent standard expression on the right.
 
-.. code-block:: python
+.. code-block:: bash
 
     simplified            standard
     --------------------  ------------------------------------

doc/signac.contrib.rst

@@ -16,6 +16,8 @@ Submodules
 signac.contrib.indexing module
 ------------------------------
 
+.. currentmodule:: signac.contrib.indexing
+
 .. automodule:: signac.contrib.indexing
     :noindex:
     :members:
@@ -25,6 +27,8 @@ signac.contrib.indexing module
 signac.contrib.collection module
 --------------------------------
 
+.. currentmodule:: signac.contrib.collection
+
 .. automodule:: signac.contrib.collection
     :noindex:
     :members:
@@ -34,6 +38,8 @@ signac.contrib.collection module
 signac.contrib.errors module
 ----------------------------
 
+.. currentmodule:: signac.contrib.errors
+
 .. automodule:: signac.contrib.errors
     :members:
     :undoc-members:
@@ -42,6 +48,8 @@ signac.contrib.errors module
 signac.contrib.filesystems module
 ---------------------------------
 
+.. currentmodule:: signac.contrib.filesystems
+
 .. automodule:: signac.contrib.filesystems
     :members:
     :undoc-members:
@@ -51,6 +59,8 @@ signac.contrib.filesystems module
 signac.contrib.hashing module
 -----------------------------
 
+.. currentmodule:: signac.contrib.hashing
+
 .. automodule:: signac.contrib.hashing
     :members:
     :undoc-members:
@@ -59,6 +69,8 @@ signac.contrib.hashing module
 signac.contrib.job module
 -------------------------
 
+.. currentmodule:: signac.contrib.job
+
 .. automodule:: signac.contrib.job
     :noindex:
     :members:
@@ -68,6 +80,8 @@ signac.contrib.job module
 signac.contrib.mpipool module
 -----------------------------
 
+.. currentmodule:: signac.contrib.mpipool
+
 .. automodule:: signac.contrib.mpipool
     :members:
     :undoc-members:
@@ -76,6 +90,8 @@ signac.contrib.mpipool module
 signac.contrib.project module
 -----------------------------
 
+.. currentmodule:: signac.contrib.project
+
 .. automodule:: signac.contrib.project
     :noindex:
     :members:
@@ -85,6 +101,8 @@ signac.contrib.project module
 signac.contrib.utility module
 -----------------------------
 
+.. currentmodule:: signac.contrib.utility
+
 .. automodule:: signac.contrib.utility
     :members:
     :undoc-members:

doc/signac.rst

@@ -1,14 +1,15 @@
 .. _api:
 
+===
 API
 ===
 
-The complete **signac** application interface (API).
+The complete **signac** application programming interface (API).
 
 Command Line Interface
-----------------------
+======================
 
-Some core **signac** functions are -- in addition to the Python interface -- accessible
+Some core **signac** functions are---in addition to the Python interface---accessible
 directly via the ``$ signac`` command.
 
 For more information, please see ``$ signac --help``.
@@ -33,20 +34,119 @@ For more information, please see ``$ signac --help``.
       -y, --yes             Answer all questions with yes. Useful for scripted
                             interaction.
 
-Module contents
----------------
+
+Python API
+==========
+
+.. _python-api-project:
+
+Project
+-------
+.. currentmodule:: signac
+
+.. autoclass:: Project
+
+.. rubric:: Attributes
+
+.. autosummary::
+
+    ~Project.build_job_search_index
+    ~Project.build_job_statepoint_index
+    ~Project.check
+    ~Project.clone
+    ~Project.config
+    ~Project.create_access_module
+    ~Project.create_linked_view
+    ~Project.detect_schema
+    ~Project.doc
+    ~Project.document
+    ~Project.dump_statepoints
+    ~Project.find_job_documents
+    ~Project.find_job_ids
+    ~Project.find_jobs
+    ~Project.find_statepoints
+    ~Project.fn
+    ~Project.get_id
+    ~Project.get_statepoint
+    ~Project.groupby
+    ~Project.groupbydoc
+    ~Project.index
+    ~Project.isfile
+    ~Project.min_len_unique_id
+    ~Project.num_jobs
+    ~Project.open_job
+    ~Project.read_statepoints
+    ~Project.repair
+    ~Project.reset_statepoint
+    ~Project.root_directory
+    ~Project.sync
+    ~Project.update_cache
+    ~Project.update_statepoint
+    ~Project.workspace
+    ~Project.write_statepoints
+
+
+.. autoclass:: Project
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: Job
+
+.. _python-api-job:
+
+Job
+---
+.. currentmodule:: signac.contrib.job
+
+.. autoclass:: Job
+
+.. rubric:: Attributes
+
+.. autosummary::
+
+    ~Job.clear
+    ~Job.close
+    ~Job.doc
+    ~Job.document
+    ~Job.fn
+    ~Job.get_id
+    ~Job.init
+    ~Job.isfile
+    ~Job.move
+    ~Job.open
+    ~Job.remove
+    ~Job.reset
+    ~Job.reset_statepoint
+    ~Job.sp
+    ~Job.statepoint
+    ~Job.sync
+    ~Job.update_statepoint
+    ~Job.workspace
+    ~Job.ws
+
+
+.. autoclass:: signac.contrib.job.Job
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Signac
+------
 
 .. automodule:: signac
     :members:
     :undoc-members:
     :show-inheritance:
+    :exclude-members: Project
 
 
 .. automodule:: signac.cite
     :members:
 
+
 Subpackages
------------
+===========
 
 .. toctree::
 

signac/contrib/collection.py

@@ -265,7 +265,7 @@ class Collection(object):
     By default a collection object will reside in memory. However, it is
     possible to manage a collection associated to a file on disk. To open
     a collection which is associated with a file on disk, use the
-    :py:meth:`.open` class method:
+    :py:meth:`Collection.open` class method:
 
     .. code-block:: python
 
@@ -849,9 +849,9 @@ def open(cls, filename, mode='a+'):
         the file if it does not exist yet.
 
         Modifications to the file will be written to the file when the
-        :py:meth:`.flush` method is called or the collection is explicitly
-        closed by calling the :py:meth:`.close` method or implicitly by
-        leaving the `with`-clause:
+        :py:meth:`~Collection.flush` method is called or the collection is
+        explicitly closed by calling the :py:meth:`Collection.close` method or
+        implicitly by leaving the `with`-clause:
 
         .. code-block:: python
 
@@ -874,7 +874,8 @@ def flush(self):
         """Write all changes to the associated file.
 
         If the collection instance is associated with a file-object,
-        calling the :py:meth:`~.flush` method will write all changes to this file.
+        calling the :py:meth:`~Collection.flush` method will write all changes
+        to this file.
 
         This method is also called when the collection is explicitly or
         implicitly closed.

signac/contrib/job.py

@@ -39,7 +39,7 @@ class Job(object):
     """The job instance is a handle to the data of a unique statepoint.
 
     Application developers should usually not need to directly
-    instantiate this class, but use :meth:`~.project.Project.open_job`
+    instantiate this class, but use :meth:`~signac.Project.open_job`
     instead."""
     FN_MANIFEST = 'signac_statepoint.json'
     """The job's manifest filename.
@@ -94,7 +94,7 @@ def workspace(self):
 
     @property
     def ws(self):
-        "The job's workspace directory."
+        """Alias for :attr:`.workspace`."""
         return self.workspace()
 
     def reset_statepoint(self, new_statepoint):
@@ -183,7 +183,8 @@ def update_statepoint(self, update, overwrite=False):
 
     @property
     def statepoint(self):
-        "Access the job's state point as attribute dictionary."
+        """Access the job's state point as attribute dictionary.
+        """
         if self._sp is None:
             self._sp = SyncedAttrDict(self._statepoint, parent=_sp_save_hook(self))
         return self._sp
@@ -194,9 +195,7 @@ def statepoint(self, new_sp):
 
     @property
     def sp(self):
-        """Access the job's state point as attribute dictionary.
-
-        Alias for :attr:`.statepoint`.
+        """ Alias for :attr:`.statepoint`.
         """
         return self.statepoint
 
@@ -243,6 +242,8 @@ def document(self, new_doc):
 
     @property
     def doc(self):
+        """Alias for :attr:`~signac.contrib.job.Job.document`.
+        """
         return self.document
 
     @doc.setter

signac/contrib/project.py

@@ -283,7 +283,7 @@ def document(self, new_doc):
     def doc(self):
         """The document associated with this project.
 
-        Alias for :attr:`~.document`.
+        Alias for :attr:`~signac.Project.document`.
 
         :return: The project document handle.
         :rtype: :class:`~.JSONDict`
@@ -581,7 +581,7 @@ def groupbydoc(self, key=None, default=None):
 
         :param key:
             The statepoint grouping parameter(s) passed as a string, iterable of strings,
-            or a function that will be passed one argument, `job.document`.
+            or a function that will be passed one argument, :attr:`Job.document`.
         :type key:
             str, iterable, or function
         :param default:
@@ -1603,7 +1603,7 @@ def groupbydoc(self, key=None, default=None):
 
         :param key:
             The statepoint grouping parameter(s) passed as a string, iterable of strings,
-            or a function that will be passed one argument, `job.document`.
+            or a function that will be passed one argument, :attr:`job.document`.
         :type key:
             str, iterable, or function
         :param default: