Add documentation for docstring format (IDSIA#619)

* Add documentation for docstring format.

Also adapt docstrings in experiment file.

* Flx flake8 errors

* Add style check to ci and adapt docstrings

* Install checker in tox

* Fix generator annotation

CONTRIBUTING.rst

@@ -20,6 +20,12 @@ If you are reporting a bug, please include:
 * Any details about your local setup that might be helpful in troubleshooting.
 * Steps to reproduce the bug, and if possible a minimal example demonstrating the problem.
 
+Good first issue
+~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "good first issue"
+is a great place to get started.
+
 Fix Bugs
 ~~~~~~~~
 
@@ -39,6 +45,30 @@ Sacred could always use more documentation, whether as part of the
 official Sacred docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
+When writing docstrings, stick to the `NumPy style
+<https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`_.
+However, prefer using Python type hints, over type annotation in the docstring.
+This makes your type hints useable by type checkers and IDEs. An example docstring
+could look like this.
+
+.. code-block :: python
+
+    def add(a: int, b: int) -> int:
+        """Add two numbers.
+
+        Parameters
+        ----------
+        a
+            The first number.
+        b
+            The second number.
+
+        Returns
+        -------
+        The sum of the two numbers.
+        """
+        return a + b
+
 Submit Feedback
 ~~~~~~~~~~~~~~~
 

doc-requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx-rtd-theme
+doc8

docs/conf.py

@@ -271,3 +271,6 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+# The return type is indicated by type hints instead.
+napoleon_use_rtype = False

sacred/__about__.py

@@ -1,7 +1,4 @@
-#!/usr/bin/env python
-# coding=utf-8
-"""
-This module contains meta-information about the Sacred package.
+"""Contains meta-information about the Sacred package.
 
 It is kept simple and separate from the main module, because this information
 is also read by the setup.py. And during installation the sacred module cannot

sacred/arg_parser.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python
-# coding=utf-8
 """
-This module contains the command-line parsing and help for experiments.
+Contains the command-line parsing and help for experiments.
 
 The command-line interface of sacred is built on top of ``docopt``, which
 constructs a command-line parser from a usage text. Curiously in sacred we

sacred/commandline_options.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python
-# coding=utf-8
 """
-This module provides the basis for all command-line options (flags) in sacred.
+Provides the basis for all command-line options (flags) in sacred.
 
 It defines the base class CommandLineOption and the standard supported flags.
 Some further options that add observers to the run are defined alongside those.

sacred/commands.py

@@ -108,15 +108,18 @@ def _format_named_configs(named_configs, indent=2):
     return "\n".join(lines)
 
 
-def print_named_configs(ingredient):
-    """
-    Returns a command function that prints the available named configs for the
-     ingredient and all sub-ingredients and exits.
+def print_named_configs(ingredient):  # noqa: D202
+    """Returns a command that prints named configs recursively.
+
+    The command function prints the available named configs for the
+    ingredient and all sub-ingredients and exits.
 
-     The output is highlighted:
-       white: config names
-       grey:  doc
-     """
+    Example
+    -------
+    The output is highlighted:
+        white: config names
+        grey:  doc
+    """
 
     def print_named_configs():
         """Print the available named configs and exit."""

sacred/config/custom_containers.py

@@ -174,9 +174,7 @@ def _readonly(self, *args, **kwargs):
 
 
 class ReadOnlyDict(ReadOnlyContainer, dict):
-    """
-    A read-only variant of a `dict`
-    """
+    """A read-only variant of a `dict`."""
 
     # Overwrite all methods that can modify a dict
     clear = ReadOnlyContainer._readonly
@@ -201,9 +199,7 @@ def __deepcopy__(self, memo):
 
 
 class ReadOnlyList(ReadOnlyContainer, list):
-    """
-    A read-only variant of a `list`
-    """
+    """A read-only variant of a `list`."""
 
     append = ReadOnlyContainer._readonly
     clear = ReadOnlyContainer._readonly
@@ -230,7 +226,8 @@ def __deepcopy__(self, memo):
 
 
 def make_read_only(o, error_message=None):
-    """
+    """Makes objects read-only.
+
     Converts every `list` and `dict` into `ReadOnlyList` and `ReadOnlyDict` in
     a nested structure of `list`s, `dict`s and `tuple`s. Does not modify `o`
     but returns the converted structure.

sacred/dependencies.py

@@ -709,7 +709,6 @@ def get_dependencies_from_pkg(globs, base_path):
 
 def gather_sources_and_dependencies(globs, base_dir=None):
     """Scan the given globals for modules and return them as dependencies."""
-
     experiment_path, main = get_main_file(globs)
 
     base_dir = base_dir or experiment_path