Merge pull request #84 from ZaxR/hotfix/readthedocs-apidoc

Add sphinxcontrib-apidoc to run sphinx-apidoc on build w/ readthedocs

bulwark/checks.py

@@ -263,21 +263,31 @@ def is_monotonic(df, items=None, increasing=None, strict=False):
         >>> import bulwark.checks as ck
         >>> import pandas as pd
         >>> df = pd.DataFrame({"incr_strict": [1, 2, 3, 4],
-                               "incr_not_strict": [1, 2, 2, 3],
-                               "decr_strict": [4, 3, 2, 1],
-                               "decr_not_strict": [3, 2, 2, 1]})
+        ...                    "incr_not_strict": [1, 2, 2, 3],
+        ...                    "decr_strict": [4, 3, 2, 1],
+        ...                    "decr_not_strict": [3, 2, 2, 1]})
         >>> items = {
-            "incr_strict": (True, True),
-            "incr_not_strict": (True, False),
-            "decr_strict": (False, True),
-            "decr_not_strict": (False, False)
-        }
+        ...     "incr_strict": (True, True),
+        ...     "incr_not_strict": (True, False),
+        ...     "decr_strict": (False, True),
+        ...     "decr_not_strict": (False, False)
+        ... }
         >>> ck.is_monotonic(df, items=items)
+           incr_strict  incr_not_strict  decr_strict  decr_not_strict
+        0            1                1            4                3
+        1            2                2            3                2
+        2            3                2            2                2
+        3            4                3            1                1
 
         All of the same cases will also pass if increasing=None,
         since only one of increasing or decreasing monotonicity is then required:
 
         >>> ck.is_monotonic(df, increasing=None, strict=False)
+           incr_strict  incr_not_strict  decr_strict  decr_not_strict
+        0            1                1            4                3
+        1            2                2            3                2
+        2            3                2            2                2
+        3            4                3            1                1
 
         The following check will fail,
         displaying a list of which (row, column)s caused the issue:

docs/conf.py

@@ -41,6 +41,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'm2r',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
@@ -49,7 +50,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'm2r',
+    'sphinxcontrib.apidoc',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -244,3 +245,15 @@
 
 # Generate autodoc stubs with summaries from code
 autosummary_generate = True
+
+# -- Options for apidoc extension ----------------------------------------------
+# Auto runs the equivalent of sphinx-apidoc -o ./docs/_source ./bulwark -f on build
+# See https://github.com/sphinx-contrib/apidoc#configuration
+apidoc_module_dir = '../bulwark'
+apidoc_output_dir = '_source'
+apidoc_excluded_paths = []
+apidoc_separate_modules = True
+# apidoc_separate_modules = False
+# apidoc_module_first = False
+# apidoc_extra_args = []
+# apidoc_toc_file = None

docs/contributing.md

@@ -164,7 +164,6 @@ with a few additional steps before releasing a new version:
 
     ```bash
     pip install -e ".[dev]"
-    sphinx-apidoc -o ./docs/_source ./bulwark -f
     cd docs
     make html
     ```

setup.py

@@ -19,9 +19,13 @@
 # Requirements placed here for convenient viewing
 install_requires = ['numpy>=1.15', 'pandas>=0.23.0']
 tests_requires = ["pytest", "pytest-cov"]
-# Upgrading to Sphinx 3.x.x requires m2r
-# to merge this pr: https://github.com/miyakogi/m2r/pull/55
-docs_requires = ["m2r", "setuptools>=30.4", "Sphinx~=2.0", "sphinx_rtd_theme"]
+docs_requires = [
+    "m2r",
+    "setuptools>=30.4",
+    "Sphinx~=2.0",  # Use of v3.x.x requires m2r upgrade: https://github.com/miyakogi/m2r/pull/55
+    "sphinxcontrib-apidoc~=0.3.0",
+    "sphinx_rtd_theme"
+]
 dev_requires = tests_requires + docs_requires + ["pre-commit", "tox"]
 
 name = project_info.NAME