Merge pull request #3943 from mathesar-foundation/manual_docs_publishing

docs/.gitignore

@@ -0,0 +1 @@
+site

docs/docs/stylesheets/extra.css

@@ -151,3 +151,17 @@
   border-bottom: 2px solid var(--md-primary-fg-color--light);
   color: var(--md-primary-bg-color--lightest);
 }
+
+/* Make header title smaller */
+.md-header__title { font-size: 0.8rem; }
+[dir="ltr"] .md-header__title { margin-left: 0; }
+
+/* Make header theme switcher smaller */
+.md-header__option .md-header__button { padding: 0.2rem; }
+.md-header__option .md-header__button { padding: 0.2rem; }
+.md-header__option .md-header__button svg { height: 1rem; width: 1rem; }
+
+/* Make version switcher smaller */
+.md-version { font-size: 0.7rem; font-weight: normal; }
+[dir="ltr"] .md-version__current { margin-left: 0.6rem; }
+.md-version__list { margin: 1.7rem 0 0 0; }

docs/mkdocs.yml

@@ -91,6 +91,7 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
+  custom_dir: overrides
 
 extra_css:
   - stylesheets/extra.css
@@ -118,3 +119,6 @@ markdown_extensions:
 
 extra:
   mathesar_version: 0.1.7
+  version:
+    provider: mike
+    alias: true

docs/overrides/404.html

@@ -0,0 +1,91 @@
+{% extends "base.html" %}
+
+{% block content %}
+  <h1>Loading...</h1>
+
+  <div class="help-404" style="display:none;">
+    <p>
+      If you followed a link here, we'd appreciate it if you would open a
+      <a href="https://github.com/mathesar-foundation/mathesar/issues">
+        GitHub issue
+      </a>
+      describing how you got here so we can fix the link.
+    </p>
+    <p>
+      You can also ask the Mathesar team for help by reaching out on
+      <a href="https://wiki.mathesar.org/community/matrix/">Matrix</a>.
+    </p>
+  </div>
+{% endblock %}
+
+{% block scripts %}
+  {{ super() }}
+  <script>
+    // @ts-check
+
+    const defaultVersionAlias = 'latest';
+
+    /**
+     * Add strings here if your docs URL has any prefixes before the version
+     * such as a repo name, a subdirectory, or a language code.
+     * 
+     * If your docs URLs look like `https://example.com/docs/en/1.0/foo/bar`
+     * then set this value to `['docs', 'en']`.
+     */
+    const pathPartsBeforeVersion = [];
+    const versionPositionInPath = pathPartsBeforeVersion.length;
+
+    /** @returns {Promise<string | undefined>} */
+    async function getRedirectionTarget() {
+      try {
+        const response = await fetch('/versions.json');
+        if (!response.ok) return undefined;
+
+        /** @type {({ version: string; title: string; aliases: string[]; })[]} */
+        const versionBlobs = await response.json();
+        const versionLikeStrings = versionBlobs.flatMap(v => [v.version, ...v.aliases]);
+
+        const url = new URL(window.location.href);
+        const pathParts = url.pathname.split('/').filter(Boolean);
+        const firstPathPart = pathParts[versionPositionInPath];
+
+        if (versionLikeStrings.includes(firstPathPart)) return undefined;
+
+        return [
+          '',
+          ...pathPartsBeforeVersion,
+          defaultVersionAlias,
+          ...pathParts,
+          url.search + url.hash
+        ].join('/');
+      }
+      catch (e) {
+        return undefined;
+      }
+    }
+
+    function setupErrorPageContent() {
+      const h1 = document.querySelector('h1');
+      if (h1) {
+        h1.textContent = 'Page Not Found';
+      }
+
+      /** @type {HTMLElement | null} */
+      const help404 = document.querySelector('.help-404');
+      if (help404) {
+        help404.style.display = 'block';
+      }
+    }
+
+    async function init() {
+      const redirectionTarget = await getRedirectionTarget();
+      if (redirectionTarget) {
+        window.location.href = redirectionTarget;
+      } else {
+        setupErrorPageContent();
+      }
+    }
+
+    init();
+  </script>
+{% endblock %}

docs/requirements.txt

@@ -3,5 +3,5 @@ mkdocs-material==8.5.11
 mkdocs-redirects==1.2.0
 mkdocs-macros-plugin==0.7.0
 mkdocs-placeholder-plugin==0.3.1
-mkdocstrings==0.24.2
-mkdocstrings-python==1.9.2
+mkdocstrings==0.25.2
+mkdocstrings-python==1.10.8