Fix docs (#24)

* Combine guides and tutorials

* rename guides to tutorials

* Removed templates

* Added examples

* Update readme

* Formatting of pyproject.toml

Author: max-models

.github/ISSUE_TEMPLATE/bug_report.md

@@ -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"
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -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,17 +37,23 @@ 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
 	cd docs && npm run preview
 
 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

.github/PULL_REQUEST_TEMPLATE.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/).

.github/workflows/docs.yml

@@ -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/).

CODE_OF_CONDUCT.md

@@ -6,3 +6,5 @@ node_modules/
 .cache/
 public/tutorials/
 src/content/docs/tutorials/*.mdx
+public/full-examples/
+src/content/docs/full-examples/

Makefile

@@ -73,6 +73,10 @@ export default defineConfig({
 					label: 'Tutorials',
 					items: [{ autogenerate: { directory: 'tutorials' } }],
 				},
+				{
+					label: 'Full examples',
+					items: [{ autogenerate: { directory: 'full-examples' } }],
+				},
 				{
 					label: 'Development',
 					items: [