DOC: auto-generate and deploy API documentation via sphinx and github pages (#186)

reviewed at #186

Author: Sheila-nk

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Build & Deploy Docs
+
+on: 
+    push:
+        branches: [ main ]
+    pull_request:
+        branches: [ main ]
+    workflow_dispatch:
+
+jobs:
+    # Build the docs
+    docs-build:
+        runs-on: ubuntu-latest
+        steps:
+        - uses: actions/checkout@v4
+        - name: Set up Python 3.12
+          uses: actions/setup-python@v5
+          with:
+            python-version: "3.12"
+            cache: 'pip'       
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            python -m pip install -e '.[doc]'
+
+        - name: Build Docs
+          run: |
+            sphinx-build -b html docs/ docs/build/
+
+        - name: Upload Artifact
+          uses: actions/upload-artifact@v4
+          with:
+            name: docs-build
+            path: docs/build/
+
+    # Deploy the docs to GitHub Pages
+    docs-deploy:
+      if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
+      runs-on: ubuntu-latest
+      needs: docs-build
+
+      # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+      permissions:
+        contents: write
+        pages: write
+
+      steps:
+        - uses: actions/checkout@v4
+        - name: Download Artifact
+          uses: actions/download-artifact@v4
+          with:
+            name: docs-build
+            path: docs/build/
+
+        - name: Deploy to GitHub pages
+          uses: JamesIves/github-pages-deploy-action@v4
+          with:
+            folder: docs/build/

.gitignore

@@ -5,3 +5,10 @@ bin/
 venv/
 .pytest_cache
 dist/
+build/
+.vscode
+**/.DS_Store
+
+# Sphinx documentation
+docs/_build/
+docs/generated/

README.md

@@ -149,7 +149,7 @@ use the command flag
 $ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
 ```
 
-See [More fine-grained control](https://github.com/scipy/scipy_doctest#More-fine-grained-control) section
+See [More fine-grained control](#more-fine-grained-control) section
 for details on how to customize the behavior.
 
 
@@ -190,7 +190,7 @@ $ python -m scipy_doctest bar.rst
 
 Notice that the command-line usage only uses the default `DTConfig` settings.
 
-
+(more-fine-grained-control)=
 ## More fine-grained control
 
 More fine-grained control of the functionality is available via the following
@@ -416,4 +416,4 @@ adding `--assert=plain` is reasonable.
 This package is work in progress. Contributions are most welcome!
 Please don't hesitate to open an issue in the tracker or send a pull request.
 
-The current location of the issue tracker is https://github.com/scipy/scipy_doctest.
+The current location of the issue tracker is <https://github.com/scipy/scipy_doctest>.

docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+from typing import Any
+
+project = 'scipy_doctest'
+copyright = '2025, Scipy Contributors'
+author = 'Scipy Contributors'
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+]
+
+source_suffix = [".rst", ".md"]
+exclude_patterns = [
+    "_build",
+    ".DS_Store"
+]
+
+default_role = "literal"
+
+html_theme = "furo"
+
+html_theme_options: dict[str, Any] = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/scipy/scipy_doctest",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,  # noqa: E501
+            "class": "",
+        },
+    ],
+    "source_repository": "https://github.com/scipy/scipy_doctest",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+always_document_param_types = True
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+
+autosummary_generate = True
+numpydoc_show_class_members = False 

docs/implementation.md

@@ -0,0 +1,15 @@
+# Implementation
+
+```{eval-rst}
+.. currentmodule:: scipy_doctest.impl
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    DTConfig
+    DTChecker
+    DTRunner
+    DebugDTRunner
+    DTFinder
+    DTParser
+```

docs/index.md

@@ -0,0 +1,10 @@
+```{include} ../README.md
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+Home <self>
+implementation.md
+plugin.md
+```

docs/plugin.md

@@ -0,0 +1,11 @@
+# Plugin
+
+```{eval-rst}
+.. currentmodule:: scipy_doctest.plugin
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    DTModule
+    DTTextfile
+```

pyproject.toml

@@ -28,6 +28,12 @@ test = [
     "scipy <= 1.14.1",   # black-list 1.5.1 ? 
     "matplotlib"
 ]
+doc = [
+    "furo==2024.8.6",
+    "myst-parser==4.0.0",
+    "sphinx==8.1.3",
+    "sphinx-copybutton==0.5.2"
+]
 
 [project.urls]
 Home = "https://github.com/scipy/scipy_doctest"

scipy_doctest/frontend.py

@@ -46,7 +46,7 @@ def find_doctests(module, strategy=None,
     Returns
     -------
     tests : list
-        A list of `doctest.DocTest`s that are defined by the module docstring,
+        A list of `doctest.DocTest` s that are defined by the module docstring,
         and by its contained objects’ docstrings. The selection is controlled
         by the `strategy` argument.
 
@@ -141,7 +141,7 @@ def testmod(m=None, name=None, globs=None, verbose=None,
         In verbose mode, the summary is detailed, else very brief (in fact,
         empty if all tests passed)
         Default is True.
-   verbose : int
+    verbose : int
         Control the run verbosity:
         0 means only report failures,
         1 means emit object names,
@@ -175,7 +175,7 @@ def testmod(m=None, name=None, globs=None, verbose=None,
     (result, history)
         `result` is a namedtuple ``TestResult(failed, attempted)``
         `history` is a dict with details of which objects were examined (the
-        keys are object names and values are individual objects' ``TestResult``s)
+        keys are object names and values are individual objects' ``TestResult`` s)
 
     Examples
     --------
@@ -204,7 +204,7 @@ def testmod(m=None, name=None, globs=None, verbose=None,
     For complex packages, prefer `strategy='api'`, which works as follows:
     - take the names of public objects from the `__all__` attribute of the package.
     - if `__all__` is not defined, take `dir(module)` and filter out names
-      which start with a leading underscore and dunders.
+    which start with a leading underscore and dunders.
     - filter out deprecated items, i.e. those which raise `DeprecationWarning`.
 
     """
@@ -306,7 +306,7 @@ def testfile(filename, module_relative=True, name=None, package=None,
         In verbose mode, the summary is detailed, else very brief (in fact,
         empty if all tests passed)
         Default is True.
-   verbose : int
+    verbose : int
         Control the run verbosity:
         0 means only report failures,
         1 means emit object names,
@@ -335,7 +335,7 @@ def testfile(filename, module_relative=True, name=None, package=None,
     (result, history)
         `result` is a namedtuple ``TestResult(failed, attempted)``
         `history` is a dict with details of which objects were examined (the
-        keys are object names and values are individual objects' ``TestResult``s)
+        keys are object names and values are individual objects' ``TestResult`` s)
     """
     # initial configuration
     if config is None:

scipy_doctest/impl.py

@@ -60,6 +60,7 @@ class DTConfig:
         >>> for test in tests:
         ...     with user_context(test):
         ...         runner.run(test)
+        
         Default is a noop.
     local_resources: dict
         If a test needs some local files, list them here. The format is
@@ -217,8 +218,13 @@ def __init__(self, *, # DTChecker configuration
 
 
 def try_convert_namedtuple(got):
-    # suppose that "got" is smth like MoodResult(statistic=10, pvalue=0.1).
-    # Then convert it to the tuple (10, 0.1), so that can later compare tuples.
+    """
+    Converts a string representation of a named tuple into a plain tuple.
+
+    Suppose that "got" is smth like MoodResult(statistic=10, pvalue=0.1).
+    Then convert it to the tuple (10, 0.1), so that can later compare tuples.
+    """
+
     num = got.count('=')
     if num == 0:
         # not a nameduple, bail out
@@ -257,6 +263,8 @@ def try_convert_printed_array(got):
 
 
 def has_masked(got):
+    """Check if a given string represents a NumPy masked array.
+    """
     return 'masked_array' in got and '--' in got
 
 
@@ -284,6 +292,20 @@ def try_split_shape_from_abbrv(s_got):
 
 
 class DTChecker(doctest.OutputChecker):
+    """
+    A drop-in replacement for `doctest.OutputChecker`.
+
+    Allows robust output comparison for numerical values and special
+    cases involving NumPy arrays, masked arrays, namedtuples, and object
+    memory addresses. It is configurable via a `DTConfig` object.
+    
+    Parameters:
+    -----------
+    config : DTConfig, optional
+        Configuration object that controls various aspects of output checking.
+        If not provided, a default `DTConfig` instance is used.
+
+    """
     obj_pattern = re.compile(r'at 0x[0-9a-fA-F]+>')
     vanilla = doctest.OutputChecker()
 
@@ -426,6 +448,25 @@ def _do_check(self, want, got, strict_check):
 
 
 class DTRunner(doctest.DocTestRunner):
+    """
+    A drop-in replacement for `doctest.DocTestRunner`.
+
+    Improves how test names are reported and allows better control over exception handling. 
+    It integrates with `DTConfig` to apply customized settings for doctest execution.
+
+    Parameters:
+    -----------
+    checker : doctest.OutputChecker, optional
+        A custom output checker, defaults to `DTConfig.CheckerKlass(config)`.
+    verbose : bool, optional
+        If `True`, enables verbose output.
+    optionflags : int, optional
+        Bitwise OR of `doctest` option flags; defaults to `DTConfig.optionflags`.
+    config : DTConfig, optional
+        A configuration object controlling doctest behavior; a default instance is used if not provided.
+
+    """
+
     DIVIDER = "\n"
 
     def __init__(self, checker=None, verbose=None, optionflags=None, config=None):
@@ -481,7 +522,8 @@ def get_history(self):
 
 
 class DebugDTRunner(DTRunner):
-    """Doctest runner which raises on a first error.
+    """
+    Doctest runner which raises an exception on the first error.
 
     Almost verbatim copy of `doctest.DebugRunner`.
     """
@@ -505,8 +547,24 @@ def report_failure(self, out, test, example, got):
 
 
 class DTFinder(doctest.DocTestFinder):
-    """A Finder with helpful defaults.
     """
+    A drop-in replacement for `doctest.DocTestFinder` with helpful defaults.
+
+    Parameters:
+    -----------
+    verbose : bool, optional
+        If `True`, enables verbose output during doctest discovery.
+    parser : doctest.DocTestParser, optional
+        A custom parser for extracting doctests; defaults to `DTParser(config)`.
+    recurse : bool, default=True
+        Whether to recursively search for doctests in nested objects.
+    exclude_empty : bool, default=True
+        Whether to exclude objects that have no doctests.
+    config : DTConfig, optional
+        A configuration object controlling doctest behavior; a default instance is used if not provided.
+
+    """
+    
     def __init__(self, verbose=None, parser=None, recurse=True,
                  exclude_empty=True, config=None):
         if config is None:
@@ -534,8 +592,21 @@ def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
 
 
 class DTParser(doctest.DocTestParser):
-    """A Parser with a stopword list.
     """
+    A drop-in replacement for `doctest.DocTestParser` with a stopword list.
+
+    It filters out stopwords, pseudocode, and random markers from doctests.
+
+    Parameters:
+    -----------
+    config : DTConfig, optional
+        A configuration object containing:
+        - `stopwords`: A list of words that signal a doctest should be ignored.
+        - `pseudocode`: A list of markers indicating non-executable code.
+        - `rndm_markers`: A list of markers indicating results may vary.
+
+    """
+
     def __init__(self, config=None):
         if config is None:
             config = DTConfig()