✨ feat: add mkdocstrings and remove sphinx from docs builds

.github/workflows/build-docs.yml

@@ -14,7 +14,7 @@ jobs:
         run: |
           python -m pip install -U pip
           pip install -U poetry
-          poetry install
+          poetry install --only docs
 
       - name: build-docs
         run: |

bin/build-docs

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 set -e
 
-bin/docs-api
 rm -rf dist/site
 poetry run mkdocs build --site-dir=dist/site

bin/check-all

@@ -24,5 +24,5 @@ echo "RUNNING PYTEST AND COVERAGE"
 poetry run coverage run -m pytest
 
 echo
-echo "BUILDING API AND MARKDOWN DOCS"
+echo "BUILDING DOCS"
 build-docs

bin/serve-docs

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 set -e
 
-bin/docs-api
 poetry run mkdocs serve

docs/.pages

@@ -3,4 +3,4 @@ nav:
   - getting_started.md
   - repo_structure.md
   - dev_setup.md
-  - reference: api
+  - reference.md

docs/reference.md

@@ -0,0 +1,3 @@
+# :books: reference
+
+::: cookie

docs/reference.md.jinja

@@ -0,0 +1,3 @@
+# :books: API reference
+
+::: {{ module_name }}

mkdocs.yml

@@ -50,6 +50,25 @@ extra_css:
 #  - js/tex-mml-chtml.js
 plugins:
   - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_inheritance_diagram: true
+            show_if_no_docstring: true
+            show_symbol_type_toc: true
+            show_symbol_type_heading: true
+            show_signature_annotations: true
+            show_submodules: true
+            show_source: true
+            group_by_category: false
+            show_category_heading: true
+            docstring_options:
+              ignore_init_summary: false
+              merge_init_into_class: true
+              separate_signature: true
   - awesome-pages
   - mkdocs-video:
       is_video: true
@@ -84,9 +103,6 @@ markdown_extensions:
   # https://github.com/microsoft/cookie-doh/security/code-scanning/4
   #  - pymdownx.arithmatex:
   #      generic: true
-  # Needed because sphinx is generating lists with 2 spaces which is not supported by mkdocs
-  # See: https://github.com/mkdocs/mkdocs/issues/545
-  - mdx_truly_sane_lists
 copyright: |
   <div id="left_copyright"><span style="color: grey;">Made with <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a></div>
   <div id="center_copyright"><a href="https://go.microsoft.com/fwlink/?LinkId=521839">Privacy & Cookies</a> | <a href="https://go.microsoft.com/fwlink/?linkid=2259814">Consumer Health Privacy</a> | <a href="https://www.microsoft.com/trademarks">Trademarks</a> | <a href="https://go.microsoft.com/fwlink/?LinkID=206977">Terms of use</a> | © 2024 Microsoft</div>