diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
deleted file mode 100644
index ff1df5b..0000000
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-name: Bug report
-about: Something does not work as documented
-title: ""
-labels: bug
-assignees: ""
----
-
-**Describe the bug**
-
-...
-
-**To reproduce**
-
-```python
-# the smallest script or command that shows the problem
-```
-
-**Expected behavior**
-
-...
-
-**Environment**
-
-- template-python version:
-- Python version:
-- OS:
-
-**Additional context**
-
-...
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index d350d6b..0000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-name: Feature request
-about: Suggest an addition or a change
-title: ""
-labels: enhancement
-assignees: ""
----
-
-**What problem does this solve?**
-
-...
-
-**Proposed solution**
-
-...
-
-**Alternatives considered**
-
-...
-
-**Additional context**
-
-...
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
deleted file mode 100644
index f81399e..0000000
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ /dev/null
@@ -1,10 +0,0 @@
-## Summary
-
-
-
-## Checklist
-
-- [ ] `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 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..5ad39b5 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -48,6 +48,7 @@ jobs:
run: |
uv run python docs/tools/notebooks.py execute
uv run python docs/tools/notebooks.py convert --strict
+ uv run python docs/tools/examples.py
- name: Build the site
working-directory: docs
@@ -59,9 +60,11 @@ 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 /tutorials/index.html /tutorials/example-tutorial/index.html /full-examples/index.html /full-examples/sine-wave/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/tutorials/example-tutorial/example_tutorial.ipynb
+ test -f dist/full-examples/sine-wave/plot-1.png
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/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..17cf667 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,7 @@ NOTEBOOKS = $(PYTHON) docs/tools/notebooks.py
DOCS_ENV = DOCS_PYTHON=$(shell $(PYTHON) -c "import sys; print(sys.executable)")
FORCE ?=
-.PHONY: help install test lint readme readme-check docs-install docs-notebooks docs-dev docs-build docs-preview docs-clean
+.PHONY: help install test lint readme readme-check docs-install docs-notebooks docs-examples docs-dev docs-build docs-preview docs-clean
help: ## list the targets
@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " %-16s %s\n", $$1, $$2}'
@@ -37,12 +37,17 @@ docs-notebooks: ## execute the changed tutorials and convert all of them (FORCE
$(NOTEBOOKS) execute $(if $(FORCE),--force,)
$(NOTEBOOKS) convert
+docs-examples: ## run full Python examples and generate pages with their plots
+ $(PYTHON) docs/tools/examples.py
+
docs-dev: ## live preview at http://localhost:4321/template-python/
$(NOTEBOOKS) convert
+ $(PYTHON) docs/tools/examples.py
cd docs && $(DOCS_ENV) DOCS_VALIDATE_LINKS=false npm run dev
docs-build: ## the static site in docs/dist, as in CI
$(NOTEBOOKS) convert
+ $(PYTHON) docs/tools/examples.py
cd docs && npm run check:mdx && $(DOCS_ENV) npm run build
docs-preview: ## serve docs/dist
@@ -50,4 +55,5 @@ docs-preview: ## serve docs/dist
docs-clean: ## remove generated pages, assets and build output
$(NOTEBOOKS) clean
+ rm -rf docs/src/content/docs/full-examples docs/public/full-examples
rm -rf docs/dist docs/.astro
diff --git a/README.md b/README.md
index 0cbcdcb..f424113 100644
--- a/README.md
+++ b/README.md
@@ -87,13 +87,15 @@ Commits](https://www.conventionalcommits.org/); see
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 docstrings with
+complete Python scripts in `examples/` published with their plots, 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-examples # run examples/*.py and publish their plots
make docs-dev # live preview at http://localhost:4321/template-python/
make docs-build # the static site in docs/dist
```
@@ -115,4 +117,4 @@ its release date), and add the release notes to `CHANGELOG.md`. The push
to `main` creates a GitHub release with a `vX.Y.Z` tag and publishes the
package to PyPI with trusted publishing (OIDC). The one-time PyPI and
GitHub configuration is described in the [publishing
-guide](https://max-models.github.io/template-python/development/publishing/).
+tutorial](https://max-models.github.io/template-python/development/publishing/).
diff --git a/README.qmd b/README.qmd
index 258a0b9..54224af 100644
--- a/README.qmd
+++ b/README.qmd
@@ -87,13 +87,15 @@ 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 `tutorials/` executed and published as pages, complete Python scripts in `examples/`
+published with their plots, 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-examples # run examples/*.py and publish their plots
make docs-dev # live preview at http://localhost:4321/template-python/
make docs-build # the static site in docs/dist
```
@@ -113,4 +115,4 @@ Before merging a release to `main`, update the version in `pyproject.toml`,
notes to `CHANGELOG.md`. The push to `main` creates a GitHub release with a `vX.Y.Z` tag and
publishes the package to PyPI with trusted publishing (OIDC). The one-time PyPI and GitHub
configuration is described in the
-[publishing guide](https://max-models.github.io/template-python/development/publishing/).
+[publishing tutorial](https://max-models.github.io/template-python/development/publishing/).
diff --git a/docs/.gitignore b/docs/.gitignore
index f5661a2..26a959f 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -6,3 +6,5 @@ node_modules/
.cache/
public/tutorials/
src/content/docs/tutorials/*.mdx
+public/full-examples/
+src/content/docs/full-examples/
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 871404b..9f1f357 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -73,6 +73,10 @@ export default defineConfig({
label: 'Tutorials',
items: [{ autogenerate: { directory: 'tutorials' } }],
},
+ {
+ label: 'Full examples',
+ items: [{ autogenerate: { directory: 'full-examples' } }],
+ },
{
label: 'Development',
items: [
diff --git a/docs/public/tutorials/example-tutorial/example_tutorial.ipynb b/docs/public/tutorials/example-tutorial/example_tutorial.ipynb
new file mode 100644
index 0000000..a48ed6a
--- /dev/null
+++ b/docs/public/tutorials/example-tutorial/example_tutorial.ipynb
@@ -0,0 +1,45 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "0",
+ "metadata": {},
+ "source": [
+ "# Example guide\n",
+ "\n",
+ "Run a small example and view its output."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "1",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(\"Example guide published in the docs!\")"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.13.3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro
index d757699..6cf8e6e 100644
--- a/docs/src/components/Header.astro
+++ b/docs/src/components/Header.astro
@@ -15,6 +15,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: 'Full examples', href: withBase('/full-examples/'), section: withBase('/full-examples/') },
{ 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..1206b9d 100644
--- a/docs/src/components/NotebookHeader.astro
+++ b/docs/src/components/NotebookHeader.astro
@@ -12,6 +12,7 @@ export interface Props {
status?: 'executed' | 'not run';
}
const { download, source, status = 'executed' } = Astro.props;
+const filename = download.split('/').at(-1) ?? 'tutorial.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 = {
---
+
+