Most recent updates mirroring DLC

Author: kushalbakshi

.gitignore

@@ -81,6 +81,7 @@ ENV/
 
 # mkdocs documentation
 /site
+site
 
 # mypy
 .mypy_cache/

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
 
+## [0.2.0] - 2022-10-21
++ Add - mkdocs deployment with workflow API docs
+
 ## [0.1.3] - 2022-10-11
 + Update - CICD workflows for PyPI release
 
@@ -16,6 +19,7 @@ Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and
 + Add - Load data acquired with Miniscope-DAQ-V3
 + Add - Load data analyzed with MiniscopeAnalysis
 
+[0.2.0]: https://github.com/datajoint/element-miniscope/releases/tag/0.2.0
 [0.1.3]: https://github.com/datajoint/element-miniscope/releases/tag/0.1.3
 [0.1.2]: https://github.com/datajoint/element-miniscope/releases/tag/0.1.2
 [0.1.1]: https://github.com/datajoint/element-miniscope/releases/tag/0.1.1

docs/mkdocs.yaml

@@ -1,18 +1,49 @@
 # ---------------------- PROJECT SPECIFIC ---------------------------
 
-site_name: Element Miniscope
+site_name: DataJoint Documentation
 repo_url: https://github.com/datajoint/element-miniscope
 repo_name: datajoint/element-miniscope
 nav:
   - Element Miniscope: index.md
   - Concepts: concepts.md
   - Tutorials: tutorials.md
-  - About:
-    - Changelog: about/changelog.md
+  - Citation: citation.md
   - API: api/ # defer to gen-files + literate-nav
+  - Changelog: about/changelog.md
 
-# ---------------------------- STANDARD -----------------------------
+# --------------------- NOTES TO CONTRIBUTORS -----------------------
+# 1. The above `nav` establishes the site structure. This should be
+#    more-or-less the same across Elements.
+# 2. Follow the google styleguide for best results with docstrings
+#    https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
+#    This includes adding typing suggestions to functions
+#    https://docs.python.org/3/library/typing.html
+# 3. To render the site for dev, use the following shell command
+#    ```console 
+#    MODE="LIVE" PACKAGE=element_{ELEMENT} \
+#    UPSTREAM_REPO=https://github.com/datajoint/element-{ELEMENT}.git \
+#    HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
+#    ```
+#    The Errors and Warnings mkdocs provides during the build are helpful
+#    for seeing where you may have broken links or docstring issues.
+# 4. To render your fork of the workflow repo prior to PRs, change the
+#    URL in ./docs/src/api/make_pages.py#L19
+# 5. Instead of using bash/shell comment blocks, use `console`
+# 6. Linking to headings requires [link](./relative-doc#sub-heading) format
+#    with (a) hypens instead of spaces, (b) all lowercase
+# 7. For redirect options, see 'redirects' below.
+# 8. Hard wrapping makes it easier to see changes in GitHub reviews. To
+#    get a keyboard shortcut for hard wrapping, see VSCode Rewrap extension.
+#    Be careful not to add line breaks in [multiword links](example.com)
+# 9. The mkdocs google analytics extension requires an environment variable
+#    GOOGLE_ANALYTICS_KEY, also available in LastPass. CICD with this is WIP
+# 10.To deploy this site on your fork, 
+#    (a) declare a branch called gh-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*.*.*
 
+# ---------------------------- STANDARD -----------------------------
 edit_uri: ./edit/main/docs/src
 docs_dir: ./src
 theme:
@@ -26,6 +57,7 @@ theme:
   favicon: assets/images/project-logo-color.png
   features:
     - toc.integrate
+    - content.code.annotate
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: datajoint
@@ -39,9 +71,9 @@ theme:
         name: Switch to light mode
 plugins:
   - search
-  - redirects:
-      redirect_maps:
-        "index.md": "getting_started.md"
+  # - redirects: # OPTIONAL REDIRECTS
+  #     redirect_maps:
+  #       "index.md": "getting_started.md"
   - mkdocstrings:
       default_handler: python
   - gen-files:
@@ -66,8 +98,31 @@ markdown_extensions:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  
 extra:
   generator: false # Disable watermark
+  analytics:
+    provider: google
+    property: !ENV GOOGLE_ANALYTICS_KEY
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >-
+            Thanks for your feedback!
   version:
     provider: mike
   social: