From 1bb28bb7a2a1e92ee30bc8df0c7892fe76e92fd7 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 12 Oct 2026 22:02:39 +0200 Subject: [PATCH 1/6] Combine guides and tutorials --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/docs.yml | 7 +- .github/workflows/test_tutorials.yml | 6 +- CODE_OF_CONDUCT.md | 36 - Makefile | 2 +- README.md | 6 +- README.qmd | 6 +- docs/.gitignore | 4 +- docs/astro.config.mjs | 4 +- .../example-tutorial}/example_tutorial.ipynb | 0 docs/src/components/Header.astro | 2 +- docs/src/components/NotebookHeader.astro | 33 +- docs/src/components/NotebookImage.astro | 2 +- docs/src/content/docs/development/docs.md | 10 +- .../content/docs/development/publishing.md | 2 +- docs/src/content/docs/index.mdx | 10 +- .../docs/tutorials/example-tutorial.mdx | 18 + docs/src/content/docs/tutorials/index.md | 12 - docs/src/utils/base.ts | 2 +- docs/tools/notebooks.py | 22 +- guides/example_tutorial.ipynb | 45 + guides/index.ipynb | 29 + pyproject.toml | 1 + uv.lock | 808 +++++++++++++++++- 24 files changed, 973 insertions(+), 96 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md rename {tutorials => docs/public/tutorials/example-tutorial}/example_tutorial.ipynb (100%) create mode 100644 docs/src/content/docs/tutorials/example-tutorial.mdx delete mode 100644 docs/src/content/docs/tutorials/index.md create mode 100644 guides/example_tutorial.ipynb create mode 100644 guides/index.ipynb diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f81399e..d2fc55c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,5 +6,5 @@ - [ ] `pre-commit run --all-files` and `pytest .` pass - [ ] New code has docstrings and tests -- [ ] The docs (`docs/`, tutorials or `README.qmd`) are updated where the behaviour changed +- [ ] The docs (`docs/`, guides or `README.qmd`) are updated where the behaviour changed - [ ] The commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, ...) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d24e9c4..bf44c05 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,6 +1,6 @@ name: Docs -# The Astro + Starlight site in docs/: hand-written pages, the executed tutorials and the API +# The Astro + Starlight site in docs/: hand-written pages, the executed guides and the API # reference. Built on every push and pull request; deployed to GitHub Pages from devel. on: @@ -44,7 +44,7 @@ jobs: uv sync --extra docs uv run python -m ipykernel install --user --name python3 - - name: Execute and convert the tutorials + - name: Execute and convert the guides run: | uv run python docs/tools/notebooks.py execute uv run python docs/tools/notebooks.py convert --strict @@ -59,9 +59,10 @@ jobs: - name: Smoke test the built site working-directory: docs run: | - for page in /index.html /getting-started/installation/index.html /tutorials/example-tutorial/index.html /api/app/index.html /api/app/main/index.html; do + for page in /index.html /getting-started/installation/index.html /guides/index.html /guides/example-tutorial/index.html /api/app/index.html /api/app/main/index.html; do test -f "dist$page" || { echo "missing dist$page"; exit 1; } done + test -f dist/guides/example-tutorial/example_tutorial.ipynb grep -q 'href="/template-python/' dist/index.html || { echo "links do not use the base path"; exit 1; } echo "all pages built with the /template-python base path" diff --git a/.github/workflows/test_tutorials.yml b/.github/workflows/test_tutorials.yml index 9389789..ceb033e 100644 --- a/.github/workflows/test_tutorials.yml +++ b/.github/workflows/test_tutorials.yml @@ -1,4 +1,4 @@ -name: Test Tutorials +name: Test Guides on: push: @@ -11,7 +11,7 @@ on: - devel jobs: - tutorials: + guides: runs-on: ubuntu-latest strategy: fail-fast: false @@ -33,5 +33,5 @@ jobs: uv sync --extra docs uv run python -m ipykernel install --user --name python3 - - name: Execute tutorials + - name: Execute guides run: uv run python docs/tools/notebooks.py execute --force diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index a5120de..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,36 +0,0 @@ -# Code of Conduct - -## Our pledge - -We as members, contributors and maintainers pledge to make participation in this project a -harassment-free experience for everyone, regardless of age, body size, visible or invisible -disability, ethnicity, sex characteristics, gender identity and expression, level of experience, -education, socio-economic status, nationality, personal appearance, race, religion, or sexual -identity and orientation. - -## Our standards - -Examples of behaviour that contributes to a positive environment: - -- Being respectful of differing opinions, viewpoints and experiences. -- Giving and gracefully accepting constructive feedback. -- Focusing on what is best for the project and the community. - -Examples of unacceptable behaviour: - -- Sexualised language or imagery, and sexual attention or advances of any kind. -- Trolling, insulting or derogatory comments, and personal or political attacks. -- Public or private harassment. -- Publishing others' private information without their explicit permission. - -## Enforcement - -Instances of abusive, harassing or otherwise unacceptable behaviour may be reported to the -maintainers at max.lindqvist@ipp.mpg.de. All complaints will be reviewed and investigated -promptly and fairly. Maintainers are obligated to respect the privacy and security of the -reporter of any incident. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), -version 2.1. diff --git a/Makefile b/Makefile index 1600081..cf79b34 100644 --- a/Makefile +++ b/Makefile @@ -33,7 +33,7 @@ docs-install: ## Python docs extra and the npm packages $(PYTHON) -m pip install -e ".[docs]" cd docs && npm ci -docs-notebooks: ## execute the changed tutorials and convert all of them (FORCE=1 reruns all) +docs-notebooks: ## execute the changed guides and convert all of them (FORCE=1 reruns all) $(NOTEBOOKS) execute $(if $(FORCE),--force,) $(NOTEBOOKS) convert diff --git a/README.md b/README.md index 0cbcdcb..1aed7af 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ analysis](https://github.com/max-models/template-python/actions/workflows/static Template repository for Python projects: a `src/` package with a console entry point, `pytest` tests, GitHub Actions for tests, static analysis, -tutorials, documentation and PyPI publishing, and an +guides, documentation and PyPI publishing, and an [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/) documentation site. @@ -86,14 +86,14 @@ Commits](https://www.conventionalcommits.org/); see ## Build docs The documentation in `docs/` is an Astro + Starlight site: hand-written -pages, the notebooks in `tutorials/` executed and published as pages, +pages, the notebooks in `guides/` executed and published as pages, and the API reference generated from the docstrings with [starlight-pydocs](https://ewels.github.io/starlight-pydocs/). It needs Node 22 or newer. ``` bash make docs-install # npm packages and the Python docs extra -make docs-notebooks # execute tutorials/*.ipynb and convert them to pages +make docs-notebooks # execute guides/*.ipynb and convert them to pages make docs-dev # live preview at http://localhost:4321/template-python/ make docs-build # the static site in docs/dist ``` diff --git a/README.qmd b/README.qmd index 258a0b9..70bf6f1 100644 --- a/README.qmd +++ b/README.qmd @@ -16,7 +16,7 @@ format: [![Python](https://img.shields.io/pypi/pyversions/template-python)](https://pypi.org/project/template-python/) Template repository for Python projects: a `src/` package with a console entry point, -`pytest` tests, GitHub Actions for tests, static analysis, tutorials, documentation and +`pytest` tests, GitHub Actions for tests, static analysis, guides, documentation and PyPI publishing, and an [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/) documentation site. @@ -87,13 +87,13 @@ Commit messages follow [Conventional Commits](https://www.conventionalcommits.or ## Build docs The documentation in `docs/` is an Astro + Starlight site: hand-written pages, the notebooks -in `tutorials/` executed and published as pages, and the API reference generated from the +in `guides/` executed and published as pages, and the API reference generated from the docstrings with [starlight-pydocs](https://ewels.github.io/starlight-pydocs/). It needs Node 22 or newer. ```bash make docs-install # npm packages and the Python docs extra -make docs-notebooks # execute tutorials/*.ipynb and convert them to pages +make docs-notebooks # execute guides/*.ipynb and convert them to pages make docs-dev # live preview at http://localhost:4321/template-python/ make docs-build # the static site in docs/dist ``` diff --git a/docs/.gitignore b/docs/.gitignore index f5661a2..a0119f5 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -4,5 +4,5 @@ dist/ node_modules/ # generated by docs/tools/notebooks.py (regenerated in CI) .cache/ -public/tutorials/ -src/content/docs/tutorials/*.mdx +public/guides/ +src/content/docs/guides/*.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 871404b..4b49af5 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -70,8 +70,8 @@ export default defineConfig({ ], }, { - label: 'Tutorials', - items: [{ autogenerate: { directory: 'tutorials' } }], + label: 'Guides', + items: [{ autogenerate: { directory: 'guides' } }], }, { label: 'Development', diff --git a/tutorials/example_tutorial.ipynb b/docs/public/tutorials/example-tutorial/example_tutorial.ipynb similarity index 100% rename from tutorials/example_tutorial.ipynb rename to docs/public/tutorials/example-tutorial/example_tutorial.ipynb diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro index d757699..e91461d 100644 --- a/docs/src/components/Header.astro +++ b/docs/src/components/Header.astro @@ -14,7 +14,7 @@ const shouldRenderSearch = const navLinks = [ { label: 'Getting started', href: withBase('/getting-started/installation/'), section: withBase('/getting-started/') }, - { label: 'Tutorials', href: withBase('/tutorials/'), section: withBase('/tutorials/') }, + { label: 'Guides', href: withBase('/guides/'), section: withBase('/guides/') }, { label: 'Development', href: withBase('/development/docs/'), section: withBase('/development/') }, { label: 'API', href: withBase('/api/app/'), section: withBase('/api/') }, ]; diff --git a/docs/src/components/NotebookHeader.astro b/docs/src/components/NotebookHeader.astro index 56ac86e..493d69b 100644 --- a/docs/src/components/NotebookHeader.astro +++ b/docs/src/components/NotebookHeader.astro @@ -1,17 +1,18 @@ --- -// The strip at the top of a tutorial page: download the notebook and open it on GitHub +// The strip at the top of a guide page: download the notebook and open it on GitHub // (written by tools/notebooks.py). import { withBase } from '../utils/base'; export interface Props { - /** Site-root path of the downloadable notebook under public/, e.g. "/tutorials/example-tutorial/example_tutorial.ipynb". */ + /** Site-root path of the downloadable notebook under public/, e.g. "/guides/example-tutorial/example_tutorial.ipynb". */ download: string; - /** Repository path of the notebook, e.g. "tutorials/example_tutorial.ipynb". */ + /** Repository path of the notebook, e.g. "guides/example_tutorial.ipynb". */ source: string; /** "executed" (outputs from a run at build time) or "not run". */ status?: 'executed' | 'not run'; } const { download, source, status = 'executed' } = Astro.props; +const filename = download.split('/').at(-1) ?? 'guide.ipynb'; const github = `https://github.com/max-models/template-python/blob/devel/${source}`; const notes = { executed: 'Run when the site was built.', @@ -20,11 +21,35 @@ const notes = { ---
- Download notebook + Download notebook View on GitHub {notes[status]}
+ +