Skip to content

Commit 3231d4a

Browse files
lundybernardlundybernard
committed
fixup! docs/decisions
1 parent e3e1b2a commit 3231d4a

13 files changed

Lines changed: 201 additions & 647 deletions

‎docs/decisions/0001-myst-migration/0001-migrate-to-mystmd.md‎

Lines changed: 40 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
# ADR 0001 — Migrate build system from Hugo to MyST-MD
22

33
Date: 2026-05-11
4-
Accepted: 2026-05-18
54
Status: Accepted
65
Branch: lb/myst-migration
7-
Issue: scientific-python/scientific-python.org#846
86

97
## Context
108

@@ -22,16 +20,43 @@ package (pip/conda) that bundles Node internally.
2220
Replace Hugo with **`mystmd` Python package** (`pip install mystmd`,
2321
`myst build --html`) as the build tool.
2422

25-
## Options considered
23+
- Python-centric install (pip/conda-forge) [pro]
24+
- Bundles Node internally — no separate Node needed [pro]
25+
- Same `myst.yml` config as Node CLI (no extra abstraction layer) [pro]
26+
- Proven by `tools.scientific-python.org` PR #81 [pro]
27+
- Works on all considered deploy platforms [pro]
28+
- Node bundled internally — slightly opaque [con]
29+
- PyPI/conda releases may lag npm by 1–7 days [con]
2630

27-
| Option | Pros | Cons |
28-
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29-
| **Stay on Hugo** | Theme parity with sibling SP sites; no content changes needed | Hugo is not Python; MyST content conversion still desirable long-term |
30-
| **jupyter-book 2.x** | Pure Python (`pip install jupyter-book`); SP ecosystem familiar with JB; conda-forge package; handles notebook execution natively | Wraps `mystmd` under the hood — extra abstraction; config format (`_config.yml`, `_toc.yml`) is not portable to plain `myst.yml` if JB is dropped later; JB 2.x released late 2024 — docs and community experience thin; feature lag vs direct `mystmd` |
31-
| **mystmd — Node CLI** (`npm install mystmd`) | Native runtime; latest npm releases immediately; same `myst.yml` config; active ExecutableBooks development | Requires Node.js in every build environment (Netlify, RTD, CI); unfamiliar to Python contributors |
32-
| **mystmd — Python package** (`pip install mystmd`) | Python-centric install (pip/conda-forge); bundles Node internally — no separate Node needed; same `myst.yml` config as Node CLI (no extra abstraction layer); proven by `tools.scientific-python.org` PR #81; works on all considered deploy platforms | Node bundled internally — slightly opaque; PyPI/conda releases may lag npm by 1–7 days |
31+
## Other options considered
3332

34-
## Rationale for proposed decision
33+
### Stay on Hugo
34+
35+
- Theme parity with sibling SP sites [pro]
36+
- No content changes needed [pro]
37+
- Hugo is not Python [con]
38+
- MyST content conversion still desirable long-term [con]
39+
40+
### jupyter-book 2.x
41+
42+
- Pure Python (`pip install jupyter-book`) [pro]
43+
- SP ecosystem familiar with JB; conda-forge package [pro]
44+
- Handles notebook execution natively [pro]
45+
- Wraps `mystmd` under the hood — extra abstraction [con]
46+
- Config format (`_config.yml`, `_toc.yml`) is not portable to plain
47+
`myst.yml` if JB is dropped later [con]
48+
- JB 2.x released late 2024 — docs and community experience thin [con]
49+
- Feature lag vs direct `mystmd` [con]
50+
51+
### mystmd — Node CLI (`npm install mystmd`)
52+
53+
- Native runtime; latest npm releases immediately [pro]
54+
- Same `myst.yml` config [pro]
55+
- Active ExecutableBooks development [pro]
56+
- Requires Node.js in every build environment (Netlify, RTD, CI) [con]
57+
- Unfamiliar to Python contributors [con]
58+
59+
## Rationale
3560

3661
**Why not jupyter-book:** `learn.scientific-python.org` contains no Jupyter
3762
notebooks; JB's primary value (notebook execution, Sphinx integration) does not
@@ -54,7 +79,7 @@ one-line change.
5479
## Installation
5580

5681
For Netlify builds and RTD: `pip install mystmd` (no Node configuration needed
57-
in `netlify.toml`; see ADR 0007).
82+
in `netlify.toml`; see ADR 0006).
5883

5984
Local dev: install via any preferred method (pip, conda, npm — developer's
6085
choice). The repo does not mandate a specific local environment.
@@ -65,7 +90,8 @@ choice). The repo does not mandate a specific local environment.
6590
- `pip install mystmd` is the chosen delivery method; no Node toolchain required
6691
in CI or `netlify.toml`
6792
- The `scientific-python-hugo-theme` submodule is removed (see ADR 0003)
68-
- `netlify.toml` is updated to use `mystmd` (see PLAN.md Phase 6)
93+
- `netlify.toml` is updated to use `mystmd` (see ADR 0006)
6994
- Nine content files require shortcode conversion (see ADR 0002)
70-
- Footer/quicklinks are not yet supported in MyST default templates (see ADR 0005)
71-
- Other SP repos remain on Hugo until they choose to migrate (see ADR 0006)
95+
- Footer/quicklinks come from the shared `scientific-python-myst-theme`
96+
(see ADR 0007)
97+
- Other SP repos remain on Hugo until they choose to migrate (see ADR 0005)

‎docs/decisions/0001-myst-migration/0002-shortcode-mapping.md‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,32 @@
11
# ADR 0002 — Hugo shortcode → MyST directive mapping
22

33
Date: 2026-05-11
4-
Status: Proposed
4+
Status: Accepted
55
Branch: lb/myst-migration
66

77
## Context
88

9-
Nine content files use Hugo shortcodes that MyST does not understand:
9+
Nine content files use Hugo shortcodes that MyST does not understand
10+
(pre-Phase-2 names):
1011

11-
| Shortcode type | Files affected (pre-Phase-2 names) |
12-
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13-
| `{{< grid >}}` / `[[item]]` | `_index.md` (root), `contributors/_index.md`, `documentation/_index.md` |
14-
| `{{< admonition >}}` | `maintainers/_index.md`, `maintainers/interacting-with-new-contributors.md`, `maintainers/managing-conflict.md`, `maintainers/meeting_types.md`, `contributors/first-contribution.md`, `community/onboarding.md` |
12+
`{{< grid >}}` / `[[item]]`
13+
14+
- `_index.md` (root)
15+
- `contributors/_index.md`
16+
- `documentation/_index.md`
17+
18+
`{{< admonition >}}`
19+
20+
- `maintainers/_index.md`
21+
- `maintainers/interacting-with-new-contributors.md`
22+
- `maintainers/managing-conflict.md`
23+
- `maintainers/meeting_types.md`
24+
- `contributors/first-contribution.md`
25+
- `community/onboarding.md`
1526

1627
## Decision
1728

18-
Convert shortcodes in two **type-batched commits** (one per shortcode type,
19-
not one per file), using the following canonical mappings:
29+
Convert shortcodes, using the following canonical mappings:
2030

2131
```
2232
{{< grid columns="1 2 2 3" >}} → ::::{grid} 1 2 2 3
@@ -38,18 +48,13 @@ not one per file), using the following canonical mappings:
3848
:::
3949
```
4050

41-
## Options considered
51+
## Other options considered
4252

4353
- **Custom MyST plugin** to interpret Hugo TOML shortcode syntax — high effort,
4454
no value once content is converted.
45-
- **Per-file commits** — nine files but ten shortcode occurrences (one file
46-
has two grid blocks); reviewers re-read the same mapping repeatedly.
47-
- **Type-batched commits** — two diffs total; reviewers evaluate the mapping
48-
pattern once per type.
4955

5056
## Consequences
5157

52-
- Two commits in Phase 3 of the migration (see [PLAN.md](PLAN.md))
5358
- Reviewers can verify correctness by comparing rendered output against the
5459
Hugo-built site for these nine pages
5560
- `grep -rE '\{\{<' content/` returns zero matches after these commits

‎docs/decisions/0001-myst-migration/0003-remove-hugo-theme-submodule.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0003 — Remove scientific-python-hugo-theme submodule
22

33
Date: 2026-05-11
4-
Status: Proposed
4+
Status: Accepted
55
Branch: lb/myst-migration
66

77
## Context
@@ -17,20 +17,19 @@ submodule has no consumer here.
1717

1818
## Decision
1919

20-
Remove the submodule from this repo in Phase 7 of the migration.
20+
Remove the submodule from this repo.
2121

2222
```bash
2323
git submodule deinit -f themes/scientific-python-hugo-theme
2424
git rm themes/scientific-python-hugo-theme
2525
rm -rf .git/modules/themes/scientific-python-hugo-theme
2626
```
2727

28-
## Options considered
28+
## Other options considered
2929

30-
1. **Remove in this PR** — clean cut; no dead code after Hugo is gone.
31-
2. **Keep until all four SP repos migrate** — delays cleanup by months or
32-
quarters; leaves a submodule that nothing in this repo uses.
33-
3. **Vendor a snapshot** — no benefit; MyST doesn't use it.
30+
- **Keep until all four SP repos migrate** — delays cleanup by months or
31+
quarters; leaves a submodule that nothing in this repo uses.
32+
- **Vendor a snapshot** — no benefit; MyST doesn't use it.
3433

3534
## Consequences
3635

@@ -39,4 +38,4 @@ rm -rf .git/modules/themes/scientific-python-hugo-theme
3938
from their own `.gitmodules` and pin their own SHA
4039
- The upstream `scientific-python-hugo-theme` repo is not affected
4140
- A follow-up PR to the sibling repos removes their copies when they migrate
42-
(see ADR 0006)
41+
(see ADR 0005)

‎docs/decisions/0001-myst-migration/0004-consume-cookie-myst-build.md‎

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0004 — Consume the cookie MyST build
22

33
Date: 2026-05-11
4-
Status: Proposed
4+
Status: Accepted
55
Branch: lb/myst-migration
66

77
## Context
@@ -29,21 +29,18 @@ How `learn` invokes cookie's build — which `mystmd` version, installed how —
2929
a separate concern, deliberately out of scope here so that this decision stays
3030
stable if the build tooling changes.
3131

32-
## Options considered
33-
34-
1. **Consume cookie's MyST build** — chosen. Cookie owns its build; `learn`
35-
consumes the output. No duplicated build logic, no fork, and cookie's
36-
independent release cadence is preserved.
37-
2. **Vendor cookie's content into `learn`** — would collapse the two sites into
38-
a single build, removing the submodule and the two-step overlay. Discards
39-
cookie's independent release cadence and its own contributor base, and makes
40-
`learn` responsible for content it does not own. Rejected.
41-
3. **Reimplement cookie's build inside `learn`** — drive `mystmd` against
42-
cookie's sources directly rather than calling its build script. Duplicates
43-
logic cookie already maintains and silently drifts whenever cookie changes
44-
its build. Rejected.
45-
4. **Drop cookie** — would break the `/development/` path; not acceptable
46-
without a replacement.
32+
## Other options considered
33+
34+
- **Vendor cookie's content into `learn`** — would collapse the two sites into
35+
a single build, removing the submodule and the two-step overlay. Discards
36+
cookie's independent release cadence and its own contributor base, and makes
37+
`learn` responsible for content it does not own. Rejected.
38+
- **Reimplement cookie's build inside `learn`** — drive `mystmd` against
39+
cookie's sources directly rather than calling its build script. Duplicates
40+
logic cookie already maintains and silently drifts whenever cookie changes
41+
its build. Rejected.
42+
- **Drop cookie** — would break the `/development/` path; not acceptable
43+
without a replacement.
4744

4845
## Consequences
4946

‎docs/decisions/0001-myst-migration/0005-defer-footer-quicklinks.md‎

Lines changed: 0 additions & 53 deletions
This file was deleted.

docs/decisions/0001-myst-migration/0006-sibling-repo-migration.md renamed to docs/decisions/0001-myst-migration/0005-sibling-repo-migration.md

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
1-
# ADR 0006 — Sibling SP repos migrate independently
1+
# ADR 0005 — Sibling SP repos migrate independently
22

33
Date: 2026-05-11
4-
Status: Proposed
4+
Status: Accepted
55
Branch: lb/myst-migration
66

77
## Context
88

99
The Scientific Python ecosystem has four Hugo-based sites sharing the same
1010
theme submodule:
1111

12-
| Repo | Domain |
13-
| ----------------------------------------------- | ------------------------------------------- |
14-
| `scientific-python/learn.scientific-python.org` | learn.scientific-python.org ← **this repo** |
15-
| `scientific-python/scientific-python.org` | scientific-python.org |
16-
| `scientific-python/blog.scientific-python.org` | blog.scientific-python.org |
17-
| `scientific-python/tools.scientific-python.org` | tools.scientific-python.org |
12+
- learn.scientific-python.org
13+
- scientific-python.org
14+
- blog.scientific-python.org
15+
- tools.scientific-python.org
1816

1917
Cross-site nav links are plain absolute URLs (not build-time references).
2018
There is no shared build pipeline coupling the repos.
@@ -23,22 +21,21 @@ There is no shared build pipeline coupling the repos.
2321
([#81](https://github.com/scientific-python/tools.scientific-python.org/pull/81),
2422
brianhawthorne, opened October 2025, stale as of May 2026). It demonstrates
2523
a working shortcode conversion and a footer implementation using
26-
`site.parts.footer:` + custom CSS (see ADR 0005 option 3).
24+
`site.parts.footer:` + custom CSS.
2725

2826
## Decision
2927

3028
`learn` migrates first. File one tracking issue per sibling repo after this
3129
PR merges, each linking to this PR as a worked example. Sibling repos adopt
3230
MyST on their own schedule.
3331

34-
## Options considered
32+
## Other options considered
3533

36-
1. **Migrate all four in lock-step** — synchronizes visual consistency; blocks
37-
`learn` on the slowest-moving repo.
38-
2. **`learn` first; siblings when ready** — proves the pattern; doesn't block
39-
SciPy 2026 deadline.
40-
3. **Wait for MyST theme parity** — defers everything until ADR 0005 follow-up
41-
is resolved; not necessary since content parity is achievable now.
34+
- **Migrate all four in lock-step** — synchronizes visual consistency; blocks
35+
`learn` on the slowest-moving repo.
36+
- **Wait for MyST theme parity** — defers everything until full footer parity
37+
lands in the shared theme (ADR 0007); not necessary since content parity is
38+
achievable now.
4239

4340
## Consequences
4441

‎docs/decisions/0001-myst-migration/0006-deploy-strategy.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# ADR 0006 — Update netlify.toml for MyST build
2+
3+
Date: 2026-05-11
4+
Status: Accepted
5+
Branch: lb/myst-migration
6+
7+
## Context
8+
9+
Both `scientific-python.org` and `learn.scientific-python.org` deploy via
10+
Netlify, which auto-deploys on push to `main` and generates PR preview deploys.
11+
The build command is defined in `netlify.toml`. The current command builds with
12+
Hugo + Dart Sass.
13+
14+
GitHub Actions runs only a lint workflow (`lint.yml`). There is no gh-pages
15+
deploy workflow.
16+
17+
## Decision
18+
19+
Update `netlify.toml` in Phase 6 of the migration: remove the Dart Sass and
20+
Hugo toolchain setup; add `pip install mystmd` before the existing
21+
`make html-all` call. Build command, publish directory, and
22+
`netlify-plugin-checklinks` are otherwise unchanged.
23+
24+
## Other options considered
25+
26+
- **Replace Netlify with gh-pages** — larger change; requires creating new
27+
GitHub Actions deploy workflows, reconfiguring DNS, and losing Netlify PR
28+
previews. Out of scope for this PR.
29+
- **Keep `netlify.toml` for the checklinks plugin only** — the Netlify
30+
checklinks plugin can be replaced by a `lychee`-based GitHub Actions job
31+
as a separate improvement; not required for this migration.
32+
- **Drop Netlify entirely; use CircleCI for builds + circleci-artifacts-
33+
redirector-action for PR previews** — demonstrated by
34+
`tools.scientific-python.org` PR #81. Viable but introduces CircleCI
35+
account dependency and is a larger infrastructure change than needed here.
36+
- **Migrate to Read the Docs** — RTD has first-class MyST/Sphinx support,
37+
built-in PR preview deploys (including for forks), and is already used
38+
widely across the Scientific Python ecosystem. Would replace Netlify
39+
entirely; requires a `.readthedocs.yaml` config and DNS reconfiguration.
40+
Resolves the fork-contributor preview gap (see Future work below)
41+
as a side effect. Not pursued in this PR — custom domain setup and RTD
42+
account provisioning are out of scope for the migration itself.
43+
44+
## Consequences
45+
46+
- Dart Sass and Hugo version pins removed from `netlify.toml`
47+
- `pip install mystmd` added before `make html-all` in the build command
48+
- Build command (`make html-all`), publish dir (`public/`), and
49+
`netlify-plugin-checklinks` are unchanged
50+
- Netlify auto-deploy and PR previews continue unchanged
51+
52+
## Future work (out of scope)
53+
54+
Two follow-up improvements; both filed as issues before this PR merges:
55+
56+
- **gh-pages PR preview**: allows contributors working from a fork to
57+
preview builds on their own GitHub Pages without requiring Netlify access.
58+
- **Replace `netlify-plugin-checklinks` with a `lychee`-based GitHub Actions
59+
job**: keeps link checking in CI, removes the Netlify plugin dependency.

0 commit comments

Comments
 (0)