basic docs with mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Deploy mkdocs site to Pages
+
+on:
+  # Runs on pushes targeting main or any branch named docs/*
+  push:
+    branches:
+    - "main"
+    - "docs/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+      - name: Build with mkdocs
+        run: mkdocs build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/API.md

@@ -0,0 +1 @@
+::: pytest_doctest_mkdocstrings.patch_doctest

docs/index.md

@@ -0,0 +1,39 @@
+# pytest-doctest-mkdocstrings
+
+A pytest plugin that allows you to use doctest and enclose your example code blocks in ` ``` ` codeblocks (e.g. when building documentation with mkdocs and mkdocstring).
+
+Usually this docstring would fail doctest:
+
+```
+    """
+    A function description
+
+    Examples:
+    --------
+    ```
+    >>> x = 1
+    >>> x
+    1
+    ```
+    """
+```
+
+As doctest looks for the output
+```
+Expected:
+    1
+    ```
+Got:
+    1
+```
+
+This plugin works by mockeypatching doctests parser when pytest begins each test session and including ` ``` ` as an identifier of the end of an expected result (a `want`).
+
+It only works when doctest is invoked via pytest, not when invoking doctest directly.
+
+If you have code examples or expected results which actually contain ` ``` ` then you'll need to re-write them.
+
+## Installation
+
+1. **Strongly recommended** to set up a virtual environment first! (e.g.. `python3 -m venv .venv`, `. .venv/bin/activate`)
+1. Install with `pip install pytest-doctest-mkdocstrings`

docs/usage.md

@@ -0,0 +1,28 @@
+# Usage
+
+After installation you can invoke pytest with the command line option `--doctest-mdcodeblocks`
+
+You also need to specifically add `--doctest-modules` and/or `--doctest-glob="*.md"` to actually run doctest in your pytest session.
+
+## Command line
+
+To run pytest and doctest all modules and all .md files:
+
+```
+`pytest --doctest-mdcodeblocks --doctest-modules --doctest-glob="*.md"`
+```
+
+## Project configuration
+
+If you chose to add these options to your `pyproject.toml`, `pytest.ini`or similar:
+
+```
+[tool.pytest.ini_options]
+addopts = [
+    "--doctest-modules",
+    "--doctest-glob='*.md'",
+    "--doctest-mdcodeblocks"
+]
+```
+
+then use `pytest --no-doctest-mdcodeblocks` to temporarily override the setting.

mkdocs.yml

@@ -0,0 +1,61 @@
+site_name: "pytest-docstest-mkdocstrings"
+repo_url: https://github.com/MusicalNinjaDad/pytest-docstest-mkdocstrings
+repo_name: MusicalNinjaDad/pytest-docstest-mkdocstrings
+
+watch:
+- pytest_doctest_mkdocstrings # To update live preview when docstrings change
+
+theme:
+  name: "material"
+  icon:
+    logo: material/language-markdown-outline
+  palette: # Palette toggles for auto-light-dark mode
+  - media: "(prefers-color-scheme)"
+    toggle:
+      icon: material/link
+      name: Switch to light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: default 
+    toggle:
+      icon: material/toggle-switch
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    toggle:
+      icon: material/toggle-switch-off-outline
+      name: Switch to system preference
+  features:
+    - navigation.expand
+    - navigation.path
+    - navigation.indexes
+
+plugins:
+- search
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_bases: false
+          show_root_heading: true
+          heading_level: 2
+          show_root_full_path: false
+          show_symbol_type_toc: true
+          docstring_section_style: table
+          docstring_options:
+            ignore_init_summary: true
+          merge_init_into_class: true
+
+markdown_extensions:
+- admonition
+- pymdownx.details
+- pymdownx.superfences:
+    custom_fences:
+    - name: mermaid
+      class: mermaid
+      format: !!python/name:pymdownx.superfences.fence_code_format
+
+nav:
+- Home:
+  - index.md
+- usage.md
+- API.md

pyproject.toml

@@ -36,6 +36,9 @@ where = ["."]
 
 [project.optional-dependencies]
 dev = [
+    "mkdocs",
+    "mkdocstrings[python]",
+    "mkdocs-material",
     "ruff",
     ]
 

pytest_doctest_mkdocstrings/patch_doctest.py

@@ -1,9 +1,13 @@
-# noqa: D100
+"""Implements the following pytest hooks."""
 import pytest
 
 
 def pytest_addoption(parser: pytest.Parser) -> None:
-    """Adds a commandline flag to enable handling markdown codeblocks in doctests."""
+    """
+    Adds a commandline flag to enable/disable handling of markdown codeblocks in doctests.
+    
+    Run by pytest during initialisation.
+    """
 
     collectiongroup = parser.getgroup("doctest", description="Doctest parsing")
     collectiongroup.addoption(
@@ -21,9 +25,9 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 def pytest_sessionstart(session: pytest.Session) -> None:
     """
-    Monkeypatches DocTests Regex to ignore end of codeblock marker.
+    Monkeypatches the regex in doctest.DocTestParser to consider the end of codeblock marker as the end of an example.
 
-    Run by pytest before beginning collection
+    Run by pytest before beginning test collection.
     """
     if not session.config.option.doctest_mdcodeblocks:
         return