docs: 📝 add comments and docs for the next contributor

Author: Drew Yang

README.md

@@ -39,7 +39,7 @@ Then install the required packages:
 pip install -r pip_requirements.txt
 ```
 
-Run mkdocs at http://127.0.0.1:8000/docs/:
+Run mkdocs at: http://127.0.0.1:8000/docs/
 ```bash
 # It will automatically reload the docs when changes are made
 mkdocs serve --config-file ./mkdocs.yaml
@@ -61,3 +61,32 @@ Navigate to http://127.0.0.1:8000/docs/ 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.
+
+## Mkdocs Warning Explanation
+
+> 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.
+```
+
+- We use reverse proxy to proxy our docs sites, here is the proxy flow:
+  - You hit `datajoint.com/*` on your browser
+  - It'll bring you to the reverse proxy server first, that you wouldn't notice
+  - when your URL ends with:
+    - `/` is the company page
+    - `/docs/` is the landing/navigation page hosted by datajoint/datajoint-docs's github pages
+    - `/docs/core/datajoint-python/` is the actual docs site hosted by datajoint/datajoint-python's github pages
+    - `/docs/elements/element-*/` is the actual docs site hosted by each element's github pages
+
+
+```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'?
+```
+- 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.

mkdocs.yaml

@@ -6,6 +6,8 @@ repo_name: datajoint/datajoint-docs
 repo_url: https://github.com/datajoint/datajoint-docs
 nav:
   - Welcome: index.md
+  # relative site url, not pointing to any docs in the repo
+  # it's for reverse proxy to proxy datajoint-python docs
   - DataJoint Python: core/datajoint-python/
   - DataJoint Elements:
       - elements/index.md
@@ -69,9 +71,10 @@ theme:
 plugins:
   - search
   - section-index
-  - redirects:
-      redirect_maps:
-        "index.md": "welcome.md"
+  # There is no welcome.md anymore
+  # - redirects:
+  #     redirect_maps:
+  #       "index.md": "welcome.md"
   - exclude:
       glob:
         - archive/*
@@ -85,8 +88,8 @@ markdown_extensions:
       options:
         custom_icons:
           - .overrides/.icons
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - mdx_truly_sane_lists
   - pymdownx.superfences:
       custom_fences:
@@ -103,8 +106,9 @@ markdown_extensions:
       custom_checkbox: true
 extra:
   generator: false # Disable watermark
-  version:
-    provider: mike
+  # There is no version for this doc
+  # version:
+  #   provider: mike
   social:
     - icon: main/company-logo
       link: https://www.datajoint.com

src/partnerships/dandi.md

@@ -1,6 +1,9 @@
 # Sustainability Roadmap between DataJoint Elements and DANDI Archive
 
 <figure markdown>
+  <!-- mkdocs will complain about this -->
+  <!-- since we will host on github pages, the relative ref needs to follow the structure in -->
+  <!-- the mkdocs's build dir $PROJ_DIR/site/images/, which is two directories above the html -->
   ![datajoint](../../images/company-logo-black.svg){: style="height:50px; padding-right:25px"}
   ![dandi](../../images/community-partnerships-dandi-logo.png){: style="height:83px"}
 </figure>

src/partnerships/facemap.md

@@ -1,6 +1,9 @@
 # Sustainability Roadmap between DataJoint Elements and Facemap
 
 <figure markdown>
+  <!-- mkdocs will complain about this -->
+  <!-- since we will host on github pages, the relative ref needs to follow the structure in -->
+  <!-- the mkdocs's build dir $PROJ_DIR/site/images/, which is two directories above the html -->
   ![datajoint](../../images/company-logo-black.svg){: style="height:50px; padding-right:25px"}
   ![facemap](../../images/community-partnerships-facemap-logo.png){: style="width:100px"}
 </figure>

src/partnerships/nwb.md

@@ -1,6 +1,9 @@
 # Sustainability Roadmap between DataJoint Elements and Neurodata Without Borders
 
 <figure markdown>
+  <!-- mkdocs will complain about this -->
+  <!-- since we will host on github pages, the relative ref needs to follow the structure in -->
+  <!-- the mkdocs's build dir $PROJ_DIR/site/images/, which is two directories above the html -->
   ![datajoint](../../images/company-logo-black.svg){: style="height:50px; padding-right:25px"}
   ![NWB](../../images/community-partnerships-nwb-logo.png){: style="width:300px"}
 </figure>

src/partnerships/openephysgui.md

@@ -1,6 +1,9 @@
 # Sustainability Roadmap between DataJoint Elements and Open Ephys GUI
 
 <figure markdown>
+  <!-- mkdocs will complain about this -->
+  <!-- since we will host on github pages, the relative ref needs to follow the structure in -->
+  <!-- the mkdocs's build dir $PROJ_DIR/site/images/, which is two directories above the html -->
   ![datajoint](../../images/company-logo-black.svg){: style="height:50px; padding-right:25px"}
   ![openephysgui](../../images/community-partnerships-openephysgui-logo.png){: style="height:87px"}
 </figure>

src/partnerships/suite2p.md

@@ -1,6 +1,9 @@
 # Sustainability Roadmap between DataJoint Elements and Suite2p
 
 <figure markdown>
+  <!-- mkdocs will complain about this -->
+  <!-- since we will host on github pages, the relative ref needs to follow the structure in -->
+  <!-- the mkdocs's build dir $PROJ_DIR/site/images/, which is two directories above the html -->
   ![datajoint](../../images/company-logo-black.svg){: style="height:50px; padding-right:25px"}
   ![suite2p](../../images/community-partnerships-suite2p-logo.png){: style="height:70px"}
 </figure>