add assets/make_api_docs.py

fix readme code links to repo
replace svelte-github-corner with svelte-zoo
update deps
pipe /api markdown through mdsvex instead of marked
pnpm remove marked

.github/workflows/gh-pages.yml

@@ -40,8 +40,8 @@ jobs:
 
       - name: Build site
         run: |
+          python assets/make_api_docs.py
           cd site
-          npm run make-api-docs
           npm run build
 
       - name: Upload build artifact

assets/make_api_docs.py

@@ -0,0 +1,32 @@
+import json
+import os
+from glob import glob
+from subprocess import run
+
+
+# Update auto-generated API docs. Also tweak lazydocs's markdown output for
+# - prettier badges linking to source code on GitHub
+# - remove bold tags since they break inline code
+
+pkg = json.load(open("site/package.json"))
+route = "site/src/routes/api"
+
+for path in glob(f"{route}/*.md"):
+    os.remove(path)
+
+run(
+    f"lazydocs {pkg['name']} --output-path {route} "
+    f"--no-watermark --src-base-url {pkg['repository']}/blob/main",
+    shell=True,
+)
+
+for path in glob(f"{route}/*.md"):
+    markdown = open(path).read()
+    # remove <b> tags from generated markdown as they break inline code
+    markdown = markdown.replace("<b>", "").replace("</b>", "")
+    # improve style of badges linking to source code on GitHub
+    markdown = markdown.replace(
+        'src="https://img.shields.io/badge/-source-cccccc?style=flat-square"',
+        'src="https://img.shields.io/badge/source-blue?style=flat" alt="source link"',
+    )
+    open(path, "w").write(markdown)

pymatviz/histograms.py

@@ -34,7 +34,7 @@ def residual_hist(
             targets - model predictions.
         ax (Axes, optional): matplotlib Axes on which to plot. Defaults to None.
         xlabel (str, optional): x-axis label. Defaults to
-            'Residual ($y_\mathrm{true} - y_\mathrm{pred}$)
+            `'Residual ($y_\mathrm{true} - y_\mathrm{pred}$'`)
         **kwargs: Additional keyword arguments to pass to matplotlib.Axes.
 
     Returns:

pymatviz/parity.py

@@ -266,7 +266,7 @@ def residual_vs_actual(
         ax (Axes, optional): matplotlib Axes on which to plot. Defaults to None.
         xlabel (str, optional): x-axis label. Defaults to "Actual value".
         ylabel (str, optional): y-axis label. Defaults to
-            'Residual ($y_\mathrm{true} - y_\mathrm{pred}$)'.
+            `'Residual ($y_\mathrm{true} - y_\mathrm{pred}$)'`.
         **kwargs: Additional keyword arguments passed to plt.plot()
 
     Returns:

pymatviz/ptable.py

@@ -46,7 +46,7 @@ def count_elements(
     Args:
         elem_values (dict[str, int | float] | pd.Series | list[str]): Iterable of
             composition strings/objects or map from element symbols to heatmap values.
-        count_mode ('{element|fractional|reduced}_composition'):
+        count_mode ('(element|fractional|reduced)_composition'):
             Only used when elem_values is a list of composition strings/objects.
             - element_composition (default): Count elements in each composition as is,
                 i.e. without reduction or normalization.
@@ -395,14 +395,14 @@ def ptable_heatmap_plotly(
 
     Args:
         elem_values (dict[str, int | float] | pd.Series | list[str]): Map from element
-            symbols to heatmap values e.g. {"Fe": 2, "O": 3} or iterable of composition
+            symbols to heatmap values e.g. dict(Fe=2, O=3) or iterable of composition
             strings or Pymatgen composition objects.
         count_mode ("composition" | "fractional_composition" | "reduced_composition"):
             Reduce or normalize compositions before counting. See count_elements() for
             details. Only used when elem_values is list of composition strings/objects.
         colorscale (str | list[str] | list[tuple[float, str]]): Color scale for heatmap.
             Defaults to plotly.express.colors.sequential.Pinkyl. See
-            https://plotly.com/python/builtin-colorscales for names of other builtin
+            plotly.com/python/builtin-colorscales for names of other builtin
             color scales. Note e.g. colorscale="YlGn" and px.colors.sequential.YlGn are
             equivalent. Custom scales are specified as ["blue", "red"] or
             [[0, "rgb(0,0,255)"], [0.5, "rgb(0,255,0)"], [1, "rgb(255,0,0)"]].
@@ -418,19 +418,20 @@ def ptable_heatmap_plotly(
         hover_props (list[str] | dict[str, str]): Elemental properties to display in the
             hover tooltip. Can be a list of property names to display only the values
             themselves or a dict mapping names to what they should display as. E.g.
-            {"atomic_mass": "atomic weight"} will display as "atomic weight = {x}".
-            Defaults to None. Available properties are: symbol, row, column, name,
+            dict(atomic_mass="atomic weight") will display as `"atomic weight = {x}"`.
+            Defaults to None.
+            Available properties are: symbol, row, column, name,
             atomic_number, atomic_mass, n_neutrons, n_protons, n_electrons, period,
             group, phase, radioactive, natural, metal, nonmetal, metalloid, type,
             atomic_radius, electronegativity, first_ionization, density, melting_point,
             boiling_point, number_of_isotopes, discoverer, year, specific_heat,
             n_shells, n_valence.
         hover_data (dict[str, str | int | float] | pd.Series): Map from element symbols
-            to additional data to display in the hover tooltip. {"Fe": "this shows up in
-            the hover tooltip on a new line below the element name"}. Defaults to None.
+            to additional data to display in the hover tooltip. dict(Fe="this appears in
+            the hover tooltip on a new line below the element name"). Defaults to None.
         font_colors (list[str]): One color name or two for [min_color, max_color].
-            min_color is applied to annotations for heatmap values
-            < (max_val - min_val) / 2. Defaults to ["black"].
+            min_color is applied to annotations with heatmap values less than
+            (max_val - min_val) / 2. Defaults to ["black"].
         gap (float): Gap in pixels between tiles of the periodic table. Defaults to 5.
         font_size (int): Element symbol and heat label text size. Any valid CSS size
             allowed. Defaults to None, meaning automatic font size based on plot size.

pymatviz/utils.py

@@ -2,7 +2,7 @@
 
 import ast
 import subprocess
-from os.path import abspath, dirname
+from os.path import dirname
 from shutil import which
 from typing import Any, Literal, Sequence, Union
 
@@ -16,7 +16,7 @@
 from sklearn.metrics import r2_score
 
 
-ROOT = dirname(dirname(abspath(__file__)))
+ROOT = dirname(dirname(__file__))
 
 Array = NDArray[Union[np.float64, np.int_]]
 

site/package.json

@@ -12,34 +12,33 @@
     "build": "vite build",
     "preview": "vite preview",
     "serve": "vite build && vite preview",
-    "make-api-docs": "rm -f src/routes/api/*.md && cd .. && lazydocs pymatviz --output-path site/src/routes/api --no-watermark --src-base-url https://github.com/janosh/pymatviz/blob/main"
+    "make-api-docs": "python ../assets/make_api_docs.py"
   },
   "devDependencies": {
     "@iconify/svelte": "^3.0.1",
-    "@sveltejs/adapter-static": "1.0.0",
-    "@sveltejs/kit": "1.0.1",
+    "@sveltejs/adapter-static": "^1.0.2",
+    "@sveltejs/kit": "^1.0.13",
     "@sveltejs/vite-plugin-svelte": "^2.0.2",
-    "@typescript-eslint/eslint-plugin": "^5.47.0",
-    "@typescript-eslint/parser": "^5.47.0",
-    "eslint": "^8.30.0",
+    "@typescript-eslint/eslint-plugin": "^5.48.1",
+    "@typescript-eslint/parser": "^5.48.1",
+    "eslint": "^8.31.0",
     "eslint-plugin-svelte3": "^4.0.0",
-    "hastscript": "^7.1.0",
+    "hastscript": "^7.2.0",
     "highlight.js": "^11.7.0",
-    "marked": "^4.2.5",
     "mdsvex": "^0.10.6",
-    "prettier": "^2.8.1",
+    "prettier": "^2.8.2",
     "prettier-plugin-svelte": "^2.9.0",
     "rehype-autolink-headings": "^6.1.1",
     "rehype-slug": "^5.1.0",
-    "svelte": "^3.55.0",
-    "svelte-check": "^3.0.1",
-    "svelte-github-corner": "^0.1.0",
+    "svelte": "^3.55.1",
+    "svelte-check": "^3.0.2",
     "svelte-preprocess": "^5.0.0",
-    "svelte-toc": "^0.5.1",
+    "svelte-toc": "^0.5.2",
+    "svelte-zoo": "^0.2.0",
     "svelte2tsx": "^0.6.0",
     "tslib": "^2.4.1",
     "typescript": "^4.9.4",
-    "vite": "^4.0.3"
+    "vite": "^4.0.4"
   },
   "prettier": {
     "semi": false,

site/src/app.css

@@ -3,11 +3,15 @@
   --blue: cornflowerblue;
   --text-color: rgb(208, 208, 208);
 
-  --toc-mobile-bg: #1c0e3e;
+  --toc-mobile-bg: #0d1a1d;
+  --toc-mobile-shadow: 0 0 1em 0 black;
+  --toc-title-padding: 0 0 0 3pt;
   --toc-li-padding: 4pt 1ex;
   --toc-mobile-btn-color: white;
+  --toc-mobile-btn-bg: teal;
+  --toc-mobile-btn-padding: 1pt 2pt;
   --toc-desktop-nav-margin: 0 0 0 1em;
-  --toc-min-width: 20em;
+  --toc-min-width: 16em;
   --toc-active-bg: darkcyan;
 
   --ghc-color: var(--night);

site/src/routes/+layout.svelte

@@ -3,8 +3,8 @@
   import Footer from '$lib/Footer.svelte'
   import { repository } from '$site/package.json'
   import { onMount } from 'svelte'
-  import GitHubCorner from 'svelte-github-corner'
   import Toc from 'svelte-toc'
+  import { GitHubCorner } from 'svelte-zoo'
   import '../app.css'
 
   $: headingSelector = `main :is(${

site/src/routes/+page.svelte

@@ -1,5 +1,16 @@
 <script lang="ts">
   import Readme from '$root/readme.md'
+  import { repository } from '$site/package.json'
+  import { onMount } from 'svelte'
+
+  onMount(() => {
+    for (const link of [
+      ...document.querySelectorAll(`a:has(code)`),
+    ] as HTMLAnchorElement[]) {
+      const path = link.href.split(`/`).slice(-2).join(`/`)
+      link.href = `${repository}/blob/main/${path}`
+    }
+  })
 </script>
 
 <Readme />

site/src/routes/api/+page.svelte

@@ -1,10 +1,8 @@
-<script lang="ts">
-  export let data
-</script>
-
 <h1 class="toc-exclude">API</h1>
 
-{@html data.html}
+{#each Object.values(import.meta.glob(`./*.md`, { eager: true })) as file}
+  <svelte:component this={file?.default} />
+{/each}
 
 <style>
   /* select all but first module h1s */