docs: enhance documentation styling and configuration

- Add CSS files for improved fonts, API navigation, and material design
- Include MathJax support for mathematical expressions
- Update mkdocs configuration with better styling and plugins
- Remove unused documentation generation scripts
- Optimize theme features and markdown extensions

Author: liblaf

.cspell.json

@@ -3,16 +3,17 @@
   "version": "0.2",
   "language": "en",
   "words": [
+    "arithmatex",
     "asyncio",
     "cuda",
     "cython",
     "direnv",
     "dmypy",
-    "dsanders",
     "elif",
-    "envrc",
+    "fieldz",
     "getattr",
     "hynek",
+    "inlinehilite",
     "ipynb",
     "ipython",
     "libc",
@@ -26,6 +27,7 @@
     "pixi",
     "pybuilder",
     "pycache",
+    "pydantic",
     "pydocstyle",
     "pyenv",
     "pyflow",

docs/css/fonts.css

@@ -0,0 +1,11 @@
+/* ref: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/ */
+/* TODO: choose fonts */
+:root {
+  --md-text-font:
+    "Roboto", "Verdana", "Arial", "Helvetica", sans-serif, ui-sans-serif,
+    system-ui, "Segoe UI Emoji", "Noto Color Emoji", emoji;
+  --md-code-font:
+    "MonaspiceNe Nerd Font", "CaskaydiaCove Nerd Font", "FiraCode Nerd Font",
+    "Monaspace Neon", "Cascadia Code", "FiraCode", "JetBrains Mono",
+    ui-monospace, monospace, "Segoe UI Emoji", "Noto Color Emoji", emoji;
+}

docs/css/mkdocstrings/api-autonav.css

@@ -0,0 +1,4 @@
+/* ref: https://github.com/tlambert03/mkdocs-api-autonav */
+nav.md-nav code.doc-symbol.doc-symbol-nav {
+  margin-right: 0.25em;
+}

docs/css/mkdocstrings/material.css

@@ -0,0 +1,77 @@
+/* ref: https://mkdocstrings.github.io/python/usage/customization/#material */
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: 0.05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: " ";
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+/* Tree-like output for backlinks. */
+.doc-backlink-list {
+  --tree-clr: var(--md-default-fg-color);
+  --tree-font-size: 1rem;
+  --tree-item-height: 1;
+  --tree-offset: 1rem;
+  --tree-thickness: 1px;
+  --tree-style: solid;
+  display: grid;
+  list-style: none !important;
+}
+
+.doc-backlink-list li > span:first-child {
+  text-indent: 0.3rem;
+}
+.doc-backlink-list li {
+  padding-inline-start: var(--tree-offset);
+  border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+  position: relative;
+  margin-left: 0 !important;
+
+  &:last-child {
+    border-color: transparent;
+  }
+  &::before {
+    content: "";
+    position: absolute;
+    top: calc(
+      var(--tree-item-height) / 2 * -1 * var(--tree-font-size) +
+        var(--tree-thickness)
+    );
+    left: calc(var(--tree-thickness) * -1);
+    width: calc(var(--tree-offset) + var(--tree-thickness) * 2);
+    height: calc(var(--tree-item-height) * var(--tree-font-size));
+    border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+    border-bottom: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+  }
+  &::after {
+    content: "";
+    position: absolute;
+    border-radius: 50%;
+    background-color: var(--tree-clr);
+    top: calc(var(--tree-item-height) / 2 * 1rem);
+    left: var(--tree-offset);
+    translate: calc(var(--tree-thickness) * -1) calc(var(--tree-thickness) * -1);
+  }
+}

…rings/syntax-highlight-in-signatures.css …rings/syntax-highlight-in-signatures.csstemplate/docs/css/mkdocstrings/syntax-highlight-in-signatures.css renamed to docs/css/mkdocstrings/syntax-highlight-in-signatures.css template/docs/css/mkdocstrings/syntax-highlight-in-signatures.css renamed to docs/css/mkdocstrings/syntax-highlight-in-signatures.css

@@ -1,7 +1,4 @@
-/* This file is @generated by <https://github.com/liblaf/copier-python>.
-   DO NOT EDIT! */
-
-/* https://mkdocstrings.github.io/python/usage/customization/#syntax-highlight-in-signatures */
+/* ref: https://mkdocstrings.github.io/python/usage/customization/#syntax-highlight-in-signatures */
 
 /* Fancier color for operators such as * and |. */
 .doc-signature .o {

docs/javascript/mathjax.js

@@ -0,0 +1,20 @@
+// ref: <https://squidfunk.github.io/mkdocs-material/reference/math/#mathjax>
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true,
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex",
+  },
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache();
+  MathJax.typesetClear();
+  MathJax.texReset();
+  MathJax.typesetPromise();
+});

template/.config/copier/mkdocs.yaml.jinja

@@ -15,18 +15,20 @@ repo_url: "https://github.com/{{ github_user }}/{{ github_repo }}"
 edit_uri: blob/main/docs/
 
 extra_css:
-  # - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/css/fonts.css
-  # - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/css/mkdocstrings/material.css
-  # - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/css/mkdocstrings/syntax-highlight-in-signatures.css
-  # I don't know why, but external CSS does not work.
-  - css/fonts.css
-  - css/mkdocstrings/material.css
-  - css/mkdocstrings/syntax-highlight-in-signatures.css
+  - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/docs/css/fonts.css
+  - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/docs/css/mkdocstrings/api-autonav.css
+  - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/docs/css/mkdocstrings/material.css
+  - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/docs/css/mkdocstrings/syntax-highlight-in-signatures.css
+
+extra_javascript:
+  - https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/docs/javascript/mathjax.js
+  - https://raw.githubusercontent.com/readthedocs/test-builds/refs/heads/mkdocs-material/docs/javascripts/readthedocs.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
 
 theme:
   name: material
   features:
-    - announce.dismiss
+    # - announce.dismiss
     - content.action.edit
     - content.action.view
     - content.code.annotate
@@ -44,7 +46,7 @@ theme:
     - navigation.instant.progress
     - navigation.path
     # - navigation.prune
-    - navigation.sections
+    # - navigation.sections
     - navigation.tabs
     - navigation.tabs.sticky
     - navigation.top
@@ -55,6 +57,7 @@ theme:
     - toc.follow
     # - toc.integrate
   palette:
+    # ref: <https://github.com/mkdocstrings/mkdocstrings/blob/d5bf4e1ed0370853f968b210ad77913faf106eed/mkdocs.yml#L70-L88>
     - media: (prefers-color-scheme)
       toggle:
         icon: material/brightness-auto
@@ -76,20 +79,26 @@ theme:
 
 plugins:
   # Built-in plugins
+  # blog:
+  # group:
+  # info:
+  meta:
+  # offline:
   # optimize: # sponsors only
+  privacy:
+  # projects:
   search:
   social:
+  tags:
   # typeset: # sponsors only
+
   # External plugins, schema provided by us
-  gen-files:
-    scripts:
-      - docs/scripts/gen-ref-pages.py
   git-committers:
     enabled: !ENV [READTHEDOCS, CI, false]
     repository: "{{ github_user }}/{{ github_repo }}"
     branch: main
-  literate-nav:
   section-index:
+
   # External plugins, schema provided by our community
   include-markdown:
   git-revision-date-localized:
@@ -103,44 +112,90 @@ plugins:
           - https://docs.python.org/3/objects.inv
         options:
           # General
+          backlinks: tree
+          extensions:
+            # Official extensions
+            - griffe_inherited_docstrings
+            - griffe_pydantic
+            - griffe_warnings_deprecated
+            # Third-party extensions
+            - docstring_inheritance.griffe
+            - griffe_fieldz
+            - griffe_generics
+            # - griffe_inherited_method_crossrefs # does not work
+          find_stubs_package: true
+          show_inheritance_diagram: true
           # Headings
+          heading_level: 1
+          show_root_heading: true
           show_symbol_type_heading: true
           show_symbol_type_toc: true
           # Members
           inherited_members: true
           filters:
-            - "!^_[^_]"
             - "!__all__"
+            - "!^_[^_]"
           summary: true
           # Docstrings
           docstring_style: google
           docstring_options:
             ignore_init_summary: true
           docstring_section_style: list
           merge_init_into_class: true
+          relative_crossrefs: true
+          scoped_crossrefs: true
           show_if_no_docstring: true
           # Signatures
+          modernize_annotations: true
           show_signature_annotations: true
           separate_signature: true
+          show_overloads: true
           signature_crossrefs: true
-  # External plugins, schema not provided
+
+  # ref: <https://mkdocstrings.github.io/autorefs/>
   autorefs:
 
+  # ref: <https://github.com/tlambert03/mkdocs-api-autonav>
+  api-autonav:
+    modules:
+      - "src/{{ wheel_package_dir }}/"
+
 markdown_extensions:
+  # ref: <https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/>
+  abbr:
   admonition:
+  attr_list:
+  def_list:
+  footnotes:
   md_in_html:
-  mdx_truly_sane_lists:
+  toc:
+    # ref: <https://github.com/mkdocstrings/mkdocstrings/blob/d5bf4e1ed0370853f968b210ad77913faf106eed/mkdocs.yml#L124-L125>
+    permalink: ¤
+
+  # ref: <https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/>
+  pymdownx.arithmatex:
+    generic: true
+  pymdownx.betterem:
+    smart_enable: all
+  pymdownx.blocks.caption:
+  pymdownx.caret:
+  pymdownx.mark:
+  pymdownx.tilde:
+  pymdownx.critic:
   pymdownx.details:
+  pymdownx.emoji:
+  pymdownx.highlight:
+  pymdownx.inlinehilite:
+  pymdownx.keys:
+  pymdownx.smartsymbols:
   pymdownx.snippets:
   pymdownx.superfences:
   pymdownx.tabbed:
     alternate_style: true
-  toc:
-    permalink: ¤
+  pymdownx.tasklist:
 
-extra:
-  version:
-    provider: mike
+  # ref: <https://github.com/radude/mdx_truly_sane_lists>
+  mdx_truly_sane_lists:
 
 watch:
   - .config/copier/mkdocs.yaml