update docs

docs/.docker/pip_requirements.txt

@@ -1,4 +1,4 @@
-mkdocs-material
+mkdocs-material==9.1.17
 mkdocs-redirects
 mkdocstrings
 mkdocstrings-python

docs/docker-compose.yaml

@@ -1,4 +1,4 @@
-# MODE="LIVE|QA|BUILD" PACKAGE=element_facemap UPSTREAM_REPO=https://github.com/datajoint/element-facemap.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
+# MODE="LIVE|QA|PUSH" PACKAGE=element_facemap UPSTREAM_REPO=https://github.com/datajoint/element-facemap.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 version: "2.4"
 services:
   docs:
@@ -29,11 +29,11 @@ services:
         export ELEMENT_UNDERSCORE=$$(echo $${PACKAGE} | sed 's/element_//g')
         export ELEMENT_HYPHEN=$$(echo $${ELEMENT_UNDERSCORE} | sed 's/_/-/g')        
         export PATCH_VERSION=$$(cat /main/$${PACKAGE}/version.py | grep -oE '\d+\.\d+\.[a-z0-9]+')
-        
+
         cp /main/notebooks/inference_tutorial.ipynb /main/docs/src/tutorials/
-        
+
         if echo "$${MODE}" | grep -i live &>/dev/null; then
-            mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
+            mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80 2>&1 | tee docs/temp_mkdocs.log
         elif echo "$${MODE}" | grep -iE "qa|push" &>/dev/null; then
             echo "INFO::Delete gh-pages branch"
             git branch -D gh-pages || true
@@ -51,4 +51,4 @@ services:
         else
             echo "Unexpected mode..."
             exit 1
-        fi
+        fi

docs/mkdocs.yaml

@@ -28,7 +28,7 @@ nav:
 # 02. Instead of designating codeblocks with bash, use console. For example..
 #     ```console
 #     cd ../my_dir
-#     ``` 
+#     ```
 # 03. Links across docs should ...
 #     A. Not involve line breaks.
 #     B. Use relative paths to docs in the same repo
@@ -48,15 +48,15 @@ nav:
 #     HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 #     ```
 # 02. The API section will pull docstrings.
-#     A. Follow google styleguide e.g., 
+#     A. Follow google styleguide e.g.,
 #        https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
 #        With typing suggestions: https://docs.python.org/3/library/typing.html
 #     B. To pull a specific workflow fork, change ./docs/src/api/make_pages.py#L19
 # 03. To see your fork of the workflow-{element} in this render, change the
 #     URL in ./docs/src/api/make_pages.py#L19 to your fork.
-# 04. To deploy this site on your fork, 
+# 04. To deploy this site on your fork,
 #     A. declare a branch called gh-pages
-#     B. go to the your fork > settings > pages 
+#     B. go to the your fork > settings > pages
 #     C. direct pages to render from the gh-pages branch at root
 #     D. push a tag to your fork with the format test*.*.*
 #
@@ -94,12 +94,12 @@ plugins:
       handlers:
         python:
           options:
-            members_order: source      
+            members_order: source
             group_by_category: false
             line_length: 88
   - gen-files:
       scripts:
-      - ./src/api/make_pages.py
+        - ./src/api/make_pages.py
   - literate-nav:
       nav_file: navigation.md
   - exclude-search:
@@ -135,9 +135,9 @@ markdown_extensions:
       generic: true
   - pymdownx.magiclink # Displays bare URLs as links
   - pymdownx.tasklist: # Renders check boxes in tasks lists
-      custom_checkbox: true  
+      custom_checkbox: true
 extra:
-  PATCH_VERSION: !ENV PATCH_VERSION 
+  PATCH_VERSION: !ENV PATCH_VERSION
   generator: false # Disable watermark
   version:
     provider: mike
@@ -173,7 +173,7 @@ extra_css:
   - assets/stylesheets/extra.css
 
 extra_javascript:
-  - https://js-na1.hs-scripts.com/23133402.js  # HubSpot chatbot
+  - https://js-na1.hs-scripts.com/23133402.js # HubSpot chatbot
   - javascripts/mathjax.js
   - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

docs/src/api/make_pages.py

@@ -24,4 +24,4 @@
     nav[path.parts] = f"{path.with_suffix('')}.md"
 
 with mkdocs_gen_files.open("api/navigation.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+    nav_file.writelines(nav.build_literate_nav())