Use NumPy style docstrings.

.gitignore

@@ -10,7 +10,6 @@ dist
 build
 eggs
 parts
-bin
 var
 sdist
 develop-eggs

bin/simple-scheduler

@@ -1,4 +1,13 @@
 #!/usr/bin/env python
+# Copyright (c) 2020 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+"""A simple scheduler implementation that works with signac-flow.
+
+The package signac-flow includes the ``simple-scheduler`` script as a simple
+model of a cluster job scheduler. The ``simple-scheduler`` script is designed
+primarily for testing and demonstration.
+"""
 import argparse
 import json
 import logging
@@ -41,6 +50,11 @@ def _get_args(script):
 
 
 def main_submit(args):
+    """Submit jobs.
+
+    Jobs are accepted from a provided filename and copied to a unique name in
+    the scheduler's inbox.
+    """
     # Try to parse args, should raise error if anything is wrong or missing
     with open(args.filename) as script:
         _get_submit_parser().parse_args(list(_get_args(script)))
@@ -152,6 +166,11 @@ def _process_queue(args, db):
 
 
 def main_run(args):
+    """Run the scheduler.
+
+    The scheduler runs multiple threads. A separate thread moves jobs from the
+    inbox to a queue. The main thread processes jobs in the queue.
+    """
     print("Start scheduler...")
     os.makedirs(args.inbox, exist_ok=True)
     os.makedirs(args.queue, exist_ok=True)
@@ -175,6 +194,10 @@ def main_run(args):
 
 
 def main_status(args):
+    """Get job status.
+
+    This returns the status of all jobs from the scheduler's database.
+    """
     with Collection.open(args.db, mode="r") as db:
         if args.json:
             print(json.dumps({doc["_id"]: doc for doc in db}, indent=4))

changelog.txt

@@ -21,6 +21,7 @@ Changed
 +++++++
 - Command line interface always uses ``--job-id`` instead of ``--jobid`` (#363, #386).
 - ``CPUEnvironment`` and ``GPUEnvironment`` classes are deprecated (#381).
+- Docstrings are now written in `numpydoc style <https://numpydoc.readthedocs.io/en/latest/format.html>`__ (#392).
 
 Version 0.11
 ============

doc/api.rst

@@ -109,17 +109,33 @@ Operations and Status
 .. autoclass:: flow.project.FlowOperation
     :show-inheritance:
     :members:
+    :special-members: __call__
 
 .. autoclass:: flow.project.FlowCmdOperation
     :show-inheritance:
     :members:
+    :special-members: __call__
 
 .. autoclass:: flow.project.JobOperation
     :members:
 
 .. autoclass:: flow.render_status.Renderer
     :members: generate_terminal_output, generate_html_output, render
 
+Labels
+------
+
+.. autoclass:: flow.label
+    :members:
+    :special-members: __call__
+
+.. autoclass:: flow.staticlabel
+    :members:
+    :special-members: __call__
+
+.. autoclass:: flow.classlabel
+    :members:
+    :special-members: __call__
 
 @flow.cmd
 ---------
@@ -135,6 +151,8 @@ Operations and Status
 ----------------
 
 .. autoclass:: directives
+    :members:
+    :special-members: __call__
 
 flow.run()
 ----------
@@ -157,13 +175,18 @@ The FlowGroup
 .. autoclass:: flow.project.FlowGroup
     :members:
 
+.. autoclass:: flow.project.FlowGroupEntry
+    :members:
+    :special-members: __call__
+
 Aggregation
 -----------
 
 .. automodule:: flow.aggregates
 
 .. autoclass:: flow.aggregates.aggregator
     :members:
+    :special-members: __call__
 
 .. autofunction:: flow.aggregates.get_aggregate_id
 

doc/conf.py

@@ -20,6 +20,7 @@ class Mock(MagicMock):
 
     @classmethod
     def __getattr__(cls, name):
+        """Get mocked attribute."""
         if name == "_mock_methods":
             return []
         return Mock()
@@ -45,6 +46,7 @@ def __getattr__(cls, name):
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
 ]