Add interrogate to enforce docstrings (#27)

* Add missing docstrings

* Update flit

* Add configuration for interrogate

* Add interrogate to tox (CI tests)

* Add interrogate badge to ReadMe

* Add information about interrogate to Contributing docs

* Add interrogate to changelog

Author: gahjelle

CHANGELOG.md

@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](https://keepachangelog1.com/en/1.0.0/)
 
 ## [Unreleased]
 
+### Added
+
+- Testing with [Interrogate](https://interrogate.readthedocs.io/) to enforce docstrings ([#27]).
+
+
 ## [1.2.0] - 2020-03-03
 
 ### Added
@@ -44,3 +49,4 @@ Initial version of `codetiming`. Version 1.0.0 corresponds to the code in the tu
 [#23]: https://github.com/realpython/codetiming/pull/23
 [#24]: https://github.com/realpython/codetiming/issues/24
 [#25]: https://github.com/realpython/codetiming/pull/25
+[#27]: https://github.com/realpython/codetiming/pull/27

CONTRIBUTING.md

@@ -65,4 +65,10 @@ Run tests using [`tox`](https://tox.readthedocs.io/). `tox` helps to enforce the
     $ pytest --cov=codetiming --cov-report=term-missing
     ```
 
+- All modules, functions, classes, and methods must have docstrings. This is enforced by [Interrogation](https://interrogate.readthedocs.io/). You can test compliance as follows:
+
+    ```
+    $ interrogate -c pyproject.toml -vv
+    ```
+
 Feel free to ask for help in your PR if you are having challenges with any of these tests.

README.md

@@ -6,6 +6,7 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/codetiming.svg)](https://pypi.org/project/codetiming/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Interrogate DocStrings](https://github.com/realpython/codetiming/blob/master/interrogate_badge.svg)](https://interrogate.readthedocs.io/)
 [![CircleCI](https://circleci.com/gh/realpython/codetiming.svg?style=shield)](https://circleci.com/gh/realpython/codetiming)
 
 Install `codetiming` from PyPI:

codetiming/_timers.py

@@ -14,6 +14,8 @@
 
 
 class Timers(UserDict):
+    """Custom dictionary that stores information about timers"""
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Add a private dictionary keeping track of all timings"""
         super().__init__(*args, **kwargs)

interrogate_badge.svg

@@ -1,46 +1,61 @@
 [build-system]
-requires = ["flit_core >=2,<3"]
+requires = ["flit_core >=2,<4"]
 build-backend = "flit_core.buildapi"
 
-[tool.flit.metadata]
-module = "codetiming"
-author = "Real Python"
-author-email = "[email protected]"
-home-page = "https://realpython.com/python-timer"
-description-file = "README.md"
-classifiers = [
-    "Development Status :: 5 - Production/Stable",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Natural Language :: English",
-    "Operating System :: MacOS",
-    "Operating System :: Microsoft",
-    "Operating System :: POSIX :: Linux",
-    "Programming Language :: Python :: 3.6",
-    "Programming Language :: Python :: 3.7",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Topic :: Education",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: System :: Monitoring",
-    "Typing :: Typed",
-]
-keywords = "timer class contextmanager decorator"
-
-# Requirements
-requires-python    = ">=3.6"
-requires           = [
-    "dataclasses; python_version < '3.7'",
-]
-
-
-[tool.flit.metadata.urls]
-"Source Code" = "https://github.com/realpython/codetiming"
-"Tutorial" = "https://realpython.com/python-timer"
-
-[tool.flit.metadata.requires-extra]
-dev                = ["black", "bump2version", "flake8", "flit", "isort", "mypy"]
-test               = ["pytest", "pytest-cov", "tox"]
+
+[tool.flit]
+
+    [tool.flit.metadata]
+    module = "codetiming"
+    author = "Real Python"
+    author-email = "[email protected]"
+    home-page = "https://realpython.com/python-timer"
+    description-file = "README.md"
+    classifiers = [
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Natural Language :: English",
+        "Operating System :: MacOS",
+        "Operating System :: Microsoft",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Topic :: Education",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Topic :: System :: Monitoring",
+        "Typing :: Typed",
+    ]
+    keywords = "timer class contextmanager decorator"
+
+    # Requirements
+    requires-python    = ">=3.6"
+    requires           = [
+        "dataclasses; python_version < '3.7'",
+    ]
+
+
+    [tool.flit.metadata.urls]
+    "Source Code" = "https://github.com/realpython/codetiming"
+    "Tutorial" = "https://realpython.com/python-timer"
+
+    [tool.flit.metadata.requires-extra]
+    dev                = ["black", "bump2version", "flake8", "flit", "interrogate", "isort", "mypy"]
+    test               = ["black", "interrogate", "pytest", "pytest-cov", "tox"]
+
+
+[tool.interrogate]
+ignore-init-method = false
+ignore-init-module = false
+ignore-magic = false
+ignore-semiprivate = false
+ignore-private = false
+ignore-module = false
+fail-under = 100
+verbose = 0
+
 
 [tool.isort]
 multi_line_output             = 3

pyproject.toml

@@ -42,9 +42,11 @@ class CustomLogger:
     """Simple class used to test custom logging capabilities in Timer"""
 
     def __init__(self):
+        """Store log messages in the .messages attribute"""
         self.messages = ""
 
     def __call__(self, message):
+        """Add a log message to the .messages attribute"""
         self.messages += message
 
 

tests/test_codetiming.py

@@ -1,6 +1,6 @@
 [tox]
 isolated_build = True
-envlist = py,black,mypy
+envlist = py, black, interrogate, mypy
 
 
 [testenv]
@@ -16,6 +16,13 @@ deps = black
 commands = python -m black --check codetiming/
 
 
+[testenv:interrogate]
+deps = interrogate
+skip_install = true
+commands =
+    interrogate --config=pyproject.toml
+
+
 [testenv:mypy]
 deps = mypy
 commands = python -m mypy --strict codetiming/