From d65d297fe16f2598c22199b84557f6765128fed6 Mon Sep 17 00:00:00 2001 From: Neil Shephard Date: Wed, 14 Jan 2026 13:15:01 +0000 Subject: [PATCH] docs: Fix mkdocs DeprecationWarning Docs [failed to build](https://github.com/AFM-SPM/AFMReader/actions/runs/20993404833/job/60344982776)... ``` WARNING - Config value 'plugins': Plugin 'mike' option 'version': Unrecognised configuration name: version INFO - MERMAID2 - Initialization arguments: {} INFO - MERMAID2 - Using javascript library (10.4.0): https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs INFO - Cleaning site directory INFO - Building documentation to directory: /home/runner/work/AFMReader/AFMReader/site INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: - api.md ERROR - Error reading page 'api/asd.md': ERROR - Invalid options: PythonOptions.__init__() got an unexpected keyword argument 'rendering' Aborted with a BuildError! Error: Process completed with exit code 1. ``` Locally we get more information (even though we are using the same versions of packages) and the pages render... ``` INFO - DeprecationWarning: Passing extra options directly under `options` is deprecated. Instead, pass them under `options.extra`, and update your templates. Current extra (unrecognized) options: rendering ``` This is caused because of the following per-file options in the `api/` files... ``` ::: AFMReader.topostats handler: python options: docstring_style: numpy rendering: show_signature_annotations: true ``` If you remove the options and just leave the reference to the API in each file, i.e. ``` ::: AFMReader.topostats ``` ...and add the options globally under the `mkdocstrings` section of `mkdocs.yml` ``` plugins: ... - mkdocstrings: handlers: python: options: docstring_style: numpy show_signature_annotations: true ``` ...then you shouldn't get the deprecation warning. --- docs/api.md | 10 ---------- docs/api/asd.md | 5 ----- docs/api/gwy.md | 5 ----- docs/api/ibw.md | 5 ----- docs/api/index.md | 12 ++++++++++++ docs/api/io.md | 5 ----- docs/api/jpk.md | 5 ----- docs/api/logging.md | 5 ----- docs/api/spm.md | 5 ----- docs/api/topostats.md | 5 ----- docs/index.md | 2 +- mkdocs.yml | 11 ++++++++++- 12 files changed, 23 insertions(+), 52 deletions(-) delete mode 100644 docs/api.md create mode 100644 docs/api/index.md diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index affca4c..0000000 --- a/docs/api.md +++ /dev/null @@ -1,10 +0,0 @@ -# API - -- [`asd.py`](api/asd.md) -- [`gwy.py`](api/gwy.md) -- [`ibw.py`](api/ibw.md) -- [`io`](api/io.md) -- [`jpk.py`](api/jpk.md) -- [`logging`](api/logging.md) -- [`spm.py`](api/spm.md) -- [`topostats.py`](api/topostats.md) diff --git a/docs/api/asd.md b/docs/api/asd.md index bce6e6c..f2db601 100644 --- a/docs/api/asd.md +++ b/docs/api/asd.md @@ -1,8 +1,3 @@ # ASD Modules ::: AFMReader.asd - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/gwy.md b/docs/api/gwy.md index 3e66aae..1b4378b 100644 --- a/docs/api/gwy.md +++ b/docs/api/gwy.md @@ -1,8 +1,3 @@ # GWY Modules ::: AFMReader.gwy - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/ibw.md b/docs/api/ibw.md index 3eb091f..116ce75 100644 --- a/docs/api/ibw.md +++ b/docs/api/ibw.md @@ -1,8 +1,3 @@ # IBW Modules ::: AFMReader.ibw - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..26c06d1 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,12 @@ +# API + +Details of the API can be found on the following pages. + +- [`asd.py`](asd.md) +- [`gwy.py`](gwy.md) +- [`ibw.py`](ibw.md) +- [`io`](io.md) +- [`jpk.py`](jpk.md) +- [`logging`](logging.md) +- [`spm.py`](spm.md) +- [`topostats.py`](topostats.md) diff --git a/docs/api/io.md b/docs/api/io.md index c42a6ce..12a24dd 100644 --- a/docs/api/io.md +++ b/docs/api/io.md @@ -1,8 +1,3 @@ # IO Modules ::: AFMReader.io - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/jpk.md b/docs/api/jpk.md index 988310d..4025f96 100644 --- a/docs/api/jpk.md +++ b/docs/api/jpk.md @@ -1,8 +1,3 @@ # JPK Modules ::: AFMReader.jpk - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/logging.md b/docs/api/logging.md index c5529dd..454e91b 100644 --- a/docs/api/logging.md +++ b/docs/api/logging.md @@ -1,8 +1,3 @@ # Logging Modules ::: AFMReader.logging - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/spm.md b/docs/api/spm.md index 1ec1c5b..a12d531 100644 --- a/docs/api/spm.md +++ b/docs/api/spm.md @@ -1,8 +1,3 @@ # SPM Modules ::: AFMReader.spm - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/api/topostats.md b/docs/api/topostats.md index 9336f60..307354d 100644 --- a/docs/api/topostats.md +++ b/docs/api/topostats.md @@ -1,8 +1,3 @@ # TopoStats Modules ::: AFMReader.topostats - handler: python - options: - docstring_style: numpy - rendering: - show_signature_annotations: true diff --git a/docs/index.md b/docs/index.md index 96a199d..6360c0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ Lab](https://pyne-lab.uk/bio/) based at the [University of Sheffield](https://sh - [Contributing](contributing.md) - [Workflow](workflow.md) - [Links](links.md) -- [API](api.md) +- [API](api/index.md) ## Citing diff --git a/mkdocs.yml b/mkdocs.yml index 3bfe743..cd703f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,7 +28,12 @@ extra: plugins: - mermaid2: - search - - mkdocstrings + - mkdocstrings: + handlers: + python: + options: + docstring_style: numpy + show_signature_annotations: true - mike: version: true @@ -44,3 +49,7 @@ markdown_extensions: - name: mermaid class: mermaid format: !!python/name:mermaid2.fence_mermaid + +watch: + - docs/ + - AFMReader/