fix: 🐛 update mkdocs

Author: Drew Yang

.gitignore

@@ -144,7 +144,7 @@ venv.bak/
 .ropeproject
 
 # mkdocs documentation
-/site
+/docs/site
 
 # mypy
 .mypy_cache/

docs/Dockerfile

@@ -1,13 +1,16 @@
-FROM python:3-alpine
+FROM python:3
 
 WORKDIR /main
-COPY mkdocs.yaml mkdocs.yaml
-COPY src/ src/
-COPY pip_requirements.txt pip_requirements.txt
+COPY ./docs/pip_requirements.txt /main/docs/pip_requirements.txt
+COPY ./datajoint /main/datajoint/
+COPY ./pyproject.toml /main/pyproject.toml
 
-ARG BOT_PAT
 RUN \
-    apk add --no-cache git && \
-    pip install --no-cache-dir -r /main/pip_requirements.txt
-    #&& \
-    #pip install --no-cache git+https://${BOT_PAT}@github.com/datajoint/mkdocs-material-insiders.git@master
+    # Install docs dependencies
+    pip install --no-cache-dir -r /main/docs/pip_requirements.txt && \
+    # Install datajoint
+    pip install --no-cache-dir -e /main/
+
+# Install dependencies first and use docker cache
+# modify docs content won't cause image rebuild
+COPY ./docs/ /main/docs/

docs/README.md

@@ -36,13 +36,22 @@ source .venv/bin/activate
 
 Then install the required packages:
 ```bash
-pip install -r pip_requirements.txt
+# go to the repo's root directory to generate API docs
+# cd ~/datajoint-python/
+
+# install mkdocs related requirements
+pip install -r ./docs/pip_requirements.txt
+# install datajoint, since API docs are generated from the package
+pip install -e .[dev]
 ```
 
-Run mkdocs at: http://127.0.0.1:8000/docs/
+Run mkdocs at: http://127.0.0.1:8000/
 ```bash
+# go to the repo's root directory to generate API docs
+# cd ~/datajoint-python/
+
 # It will automatically reload the docs when changes are made
-mkdocs serve --config-file ./mkdocs.yaml
+mkdocs serve --config-file ./docs/mkdocs.yaml
 ```
 
 ## With Docker
@@ -57,7 +66,7 @@ Then run the following:
 MODE="LIVE" docker compose up --build
 ```
 
-Navigate to http://127.0.0.1:8000/docs/ to preview the changes.
+Navigate to http://127.0.0.1:8000/ to preview the changes.
 
 This setup supports live-reloading so all that is needed is to save the markdown files
 and/or `mkdocs.yaml` file to trigger a reload.
@@ -67,10 +76,8 @@ and/or `mkdocs.yaml` file to trigger a reload.
 > TL;DR: We need to do it this way for hosting, please keep it as is.
 
 ```log
-WARNING -  A reference to 'core/datajoint-python/' is included in the 'nav' configuration, which is not found
-           in the documentation files.
-INFO    -  Doc file 'index.md' contains an unrecognized relative link './core/datajoint-python/', it was left
-           as is.
+INFO    -  Doc file 'index.md' contains an unrecognized relative link './develop', it was left as is. Did you mean
+           'develop.md'?
 ```
 
 - We use reverse proxy to proxy our docs sites, here is the proxy flow:
@@ -84,9 +91,7 @@ INFO    -  Doc file 'index.md' contains an unrecognized relative link './core/da
 
 
 ```log
-WARNING -  Doc file 'partnerships/openephysgui.md' contains a link
-           '../../images/community-partnerships-openephysgui-logo.png', but the target
-           '../images/community-partnerships-openephysgui-logo.png' is not found among documentation files.
-           Did you mean '../images/community-partnerships-openephysgui-logo.png'?
+WARNING -  Doc file 'query/operators.md' contains a link '../../../images/concepts-operators-restriction.png', but
+           the target '../../images/concepts-operators-restriction.png' is not found among documentation files.
 ```
 - We use Github Pages to host our docs, the image references needs to follow the mkdocs's build directory structure, under `site/` directory once you run mkdocs.

docs/docker-compose.yaml

@@ -1,31 +1,34 @@
-# MODE="LIVE|QA|BUILD" LATEST_TAG=$(git describe --tags --abbrev=0) docker compose up --build
+# MODE="LIVE|QA|BUILD" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git docker compose up --build
 services:
   docs:
     build:
-      context: .
-      dockerfile: Dockerfile
+      # some docs need to be dynamically generated from the datajoint PACKAGE
+      context: ..
+      dockerfile: docs/Dockerfile
     image: datajoint-python-docs
     environment:
-      - MODE
-      - LATEST_TAG
+      MODE: ${MODE:-LIVE} # specify mode: LIVE, QA, BUILD
+      # specify package to generate API docs
+      PACKAGE: ${PACKAGE:-datajoint}
+      UPSTREAM_REPO: ${UPSTREAM_REPO:-https://github.com/datajoint/datajoint-python.git}
     volumes:
       - ..:/main
     ports:
       - 8000:8000
     command:
-      - sh
+      - bash
       - -c
       - |
         set -e
         if echo "$${MODE}" | grep -i live &>/dev/null; then
-            mkdocs serve --config-file mkdocs.yaml -a 0.0.0.0:8000
+            mkdocs serve --config-file /main/docs/mkdocs.yaml -a 0.0.0.0:8000
         elif echo "$${MODE}" | grep -iE "qa|build" &>/dev/null; then
             git branch -D gh-pages || true
             git fetch $${UPSTREAM_REPO} gh-pages:gh-pages || true
-            mike deploy --config-file mkdocs.yaml -u $$LATEST_TAG latest
-            mike set-default --config-file mkdocs.yaml latest
+            mike deploy --ignore-remote-status --config-file /main/docs/mkdocs.yaml -u $$(grep -oE '\d+\.\d+' /main/$${PACKAGE}/version.py) latest
+            # mike set-default --config-file /main/docs/mkdocs.yaml latest
             if echo "$${MODE}" | grep -i qa &>/dev/null; then
-                mike serve --config-file mkdocs.yaml -a 0.0.0.0:8000
+                mike serve --config-file /main/docs/mkdocs.yaml -a 0.0.0.0:8000
             fi
         else
             echo "Unexpected mode..."

docs/src/.overrides/partials/nav.html

@@ -1,33 +1,53 @@
+<!-- Reference from: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/nav.html -->
+
+{% import "partials/nav-item.html" as item with context %}
+
+<!-- Determine classes -->
 {% set class = "md-nav md-nav--primary" %}
 {% if "navigation.tabs" in features %}
-{% set class = class ~ " md-nav--lifted" %}
+  {% set class = class ~ " md-nav--lifted" %}
 {% endif %}
 {% if "toc.integrate" in features %}
-{% set class = class ~ " md-nav--integrated" %}
+  {% set class = class ~ " md-nav--integrated" %}
 {% endif %}
-<nav class="{{ class }}" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
-    <label class="md-nav__title" for="__drawer">
-        <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}"
-            class="md-nav__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
-            {% include "partials/logo.html" %}
-        </a>
-        {#-
-        Add DataJoint home link to navigation header, otherwise unchanged
-        -#}
-        <a href="https://datajoint.com/docs/" title="DataJoint">
-            ⬅ Home
-        </a>
-    </label>
-    {% if config.repo_url %}
+
+<!-- Navigation -->
+<nav
+  class="{{ class }}"
+  aria-label="{{ lang.t('nav') }}"
+  data-md-level="0"
+>
+
+  <!-- Site title -->
+  <label class="md-nav__title" for="__drawer">
+    <a
+      href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
+      title="{{ config.site_name | e }}"
+      class="md-nav__button md-logo"
+      aria-label="{{ config.site_name }}"
+      data-md-component="logo"
+    >
+      {% include "partials/logo.html" %}
+    </a>
+    <!-- Add DataJoint home link to navigation header, otherwise unchanged -->
+    <!-- {{ config.site_name }} -->
+    <a href="https://datajoint.com/docs/" title="DataJoint">
+      ⬅ Home
+    </a>
+  </label>
+
+  <!-- Repository information -->
+  {% if config.repo_url %}
     <div class="md-nav__source">
-        {% include "partials/source.html" %}
+      {% include "partials/source.html" %}
     </div>
-    {% endif %}
-    <ul class="md-nav__list" data-md-scrollfix>
-        {% for nav_item in nav %}
-        {% set path = "__nav_" ~ loop.index %}
-        {% set level = 1 %}
-        {% include "partials/nav-item.html" %}
-        {% endfor %}
-    </ul>
-</nav>
+  {% endif %}
+
+  <!-- Navigation list -->
+  <ul class="md-nav__list" data-md-scrollfix>
+    {% for nav_item in nav %}
+      {% set path = "__nav_" ~ loop.index %}
+      {{ item.render(nav_item, path, 1) }}
+    {% endfor %}
+  </ul>
+</nav>

docs/src/api/make_pages.py

@@ -5,7 +5,7 @@
 
 import mkdocs_gen_files
 
-package = os.getenv("PACKAGE")
+package = os.getenv("PACKAGE", "datajoint")
 nav = mkdocs_gen_files.Nav()
 for path in sorted(Path(package).glob("**/*.py")):
     with mkdocs_gen_files.open(f"api/{path.with_suffix('')}.md", "w") as f:

docs/src/citation.md

@@ -4,4 +4,4 @@ If your work uses the DataJoint for Python, please cite the following manuscript
 
 - Yatsenko D, Reimer J, Ecker AS, Walker EY, Sinz F, Berens P, Hoenselaar A, Cotton RJ, Siapas AS, Tolias AS. DataJoint: managing big scientific data using MATLAB or Python. bioRxiv. 2015 Jan 1:031658. doi: https://doi.org/10.1101/031658
 
-- DataJoint for Python - [RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543) - Version `Enter version here`
+- DataJoint for Python - [RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543) - Version `Enter datajoint-python version you are using here`