SCENE template installer

.github/workflows/tests.yml

@@ -30,8 +30,14 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24.x
       - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --extra dev
       - run: uv run pytest
+        env:
+          # Also generate a project, then install, lint, test and build it: see tests/test_cli.py.
+          SCENE_TEMPLATE_E2E: "1"

.gitignore

@@ -177,7 +177,7 @@ cython_debug/
 #  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
 #  and can be added to the global gitignore or merged into this file. However, if you prefer,
-#  you could uncomment the following to ignore the enitre vscode folder
+#  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 
 # Ruff stuff:

README.md

@@ -2,15 +2,12 @@
 
 **Documentation: [scene-collaboration.github.io/CodeAndDocsTemplate](https://scene-collaboration.github.io/CodeAndDocsTemplate/)**
 
-This repository is the starting point for SCENE code projects: a template repository with packaging, formatting, tests, continuous integration and documentation already set up.
+This repository holds SCENE's code and data guidelines, and `scene-repo-template`, which creates new projects with packaging, formatting, tests, continuous integration and documentation already set up.
 
-SCENE's shared code lives in the [SCENE-Collaboration](https://github.com/SCENE-Collaboration) GitHub organisation. The template may be used for new repositories here or elsewhere in the consortium.
+SCENE's shared code lives in the [SCENE-Collaboration](https://github.com/SCENE-Collaboration) GitHub organisation. Generated projects may live there or elsewhere in the consortium.
 
-> [!NOTE]
-> **The project template will be added soon!** Please stay tuned until #1 merges.
+> **Starting a new project?** Follow [Using this template](https://scene-collaboration.github.io/CodeAndDocsTemplate/using-the-template/), step by step.
 
-
-**Documentation:**
 - [Project standards](https://scene-collaboration.github.io/CodeAndDocsTemplate/guidelines/): project layout, formatting and linting, CI, lockfiles, containers and DataJoint.
 - [Collaborating on code](https://scene-collaboration.github.io/CodeAndDocsTemplate/development-guide/): Git workflow, code style, issues, pull requests and code review.
 - [Documentation with Jupyter Book](https://scene-collaboration.github.io/CodeAndDocsTemplate/jupyter-book/), built from [`docs/`](docs/) and published to GitHub Pages.

TODO.md

@@ -1,21 +1,15 @@
 # TODO
 
-Open work and open decisions for this template.
+Open work and open decisions for this repository.
 
 ## Work
 
-- **Project generator** (`scripts/new_project.py`, stdlib only):
-  - copies an explicit allowlist of template files, never the contributed examples;
-  - renames `placeholder` everywhere `docs/guides/using-the-template.md` lists;
-  - asks which docs backend to keep: Jupyter Book (`docs/myst.yml`) or MkDocs (`api-docs/`, branch `cy/scene-docs-mkdocs`);
-  - has tests in `tests/`, run by `tests.yml` on Linux and Windows;
-  - then: rewrite `docs/guides/using-the-template.md` around it, and restore the README's directory tree, generated from its allowlist.
-- **CI on the template itself:** run the workflows on the template repository whatever its visibility, with `if: ${{ github.event.repository.is_template || !github.event.repository.private }}`, so repositories created from it keep the public-only rule. Check in a real run that `is_template` is set in the event payload.
-- **Review and test pass:** `pytest` on Windows and Linux, `pre-commit run --all-files --hook-stage manual`, a strict book build with link checking, `actionlint` and `zizmor`, the generator end to end (generate, lock, install, test, build the docs), and every page checked in light and dark mode.
+- **MkDocs backend for the generator:** `src/scene_repo_template/skeleton/mkdocs/`, from the prototype on `cy/scene-docs-mkdocs` (worktree `../CodeAndDocsTemplate-mkdocs`, `api-docs/` uncommitted). It writes `docs/`, with its own docs extra (`docs_dependencies`), docs workflow and SCENE stylesheet from `scene-palette.json`; add it to `BACKENDS` in `cli.py` and to the end-to-end docs test. The logo and favicon are in `skeleton/jupyter-book/docs/images/` because `footer.md` links them relatively; move them to `common/` only if both backends can reach them there.
+- **CI on this repository:** its workflows skip private repositories, like those of generated projects. If the new repository is private, delete the `if:` lines in `.github/workflows/` here; the skeleton's keep them.
+- **Review and test pass:** `pytest` on Windows and Linux with `SCENE_TEMPLATE_E2E=1`, `pre-commit run --all-files --hook-stage manual`, a strict book build with link checking, `actionlint` and `zizmor` on `.github/` and the skeleton's `dot-github/`, the interactive prompts by hand, and every page checked in light and dark mode.
 
 ## Decisions
 
-- **Host the MkDocs API site next to the Jupyter Book?** One Pages site per repository, so both builds would go into one artifact (book at `/`, MkDocs under `/api/`): one more step in `.github/workflows/docs.yml`, a second toolchain in `uv.lock`, two themes to keep alike. Decide once the generator offers the MkDocs option, so its output can be shown.
-- **New repository:** this work moves to a new SCENE repository; its name and visibility are open. After the move, update the repository links in `pyproject.toml` (`urls`) and `docs/myst.yml` (`github`), and in `api-docs/mkdocs.yml` if kept.
+- **New repository:** this work moves to a new SCENE repository; its name and visibility are open. After the move, update the repository links in `pyproject.toml` (`urls`), `docs/myst.yml` (`github`) and the `uvx --from` command in `docs/guides/using-the-template.md`. `uvx --from git+https://…` works without credentials only on a public repository. Do not mark it as a GitHub template repository: projects come from the generator.
 - **Footer funder line:** "Simons Foundation" now; SCENE's own wording is "supported by a Simons Foundation International grant administered by the Simons Foundation".
 - **MLAI example headers:** authors are given as initials (C. Benquet, T. Sainsbury); the permission line has no date.

docs/guides/jupyter-book.md

@@ -7,9 +7,9 @@ This template uses Jupyter Book 2. The configuration is `docs/myst.yml`.
 ## Write
 
 - Pages are Markdown files and notebooks in `docs/`; the landing page is `docs/index.md`.
-- Add a page by creating the file and listing it under `toc:` in `myst.yml`. Pages not listed there are not built.
+- Add a page by creating the file in `docs/`: every page there is built and listed in the sidebar, in alphabetical order, with folders as sections. To choose the order, add a [`toc:`](https://mystmd.org/guide/table-of-contents) to `myst.yml`; pages not listed there are then not built.
 - Images go in `docs/images/`.
-- Notebooks (`.ipynb`) can be listed like any page. They are shown with the outputs saved in them, not re-executed: [Figure 5 kinematics](../contributed-examples/MLAI/figure-5-kinematics.ipynb) is an example.
+- Notebooks (`.ipynb`) are pages like any other. They are shown with the outputs saved in them, not re-executed: [Figure 5 kinematics](../contributed-examples/MLAI/figure-5-kinematics.ipynb) is an example.
 
 ## Preview locally
 

docs/guides/using-the-template.md

@@ -1,44 +1,148 @@
 # Using this template
 
-Steps to start a new project from this repository, in order.
+`scene-repo-template` creates a new project with packaging, tests, CI and a documentation site already set up.
 
-## 1. Create your repository
+It works with uv, pip or conda; it needs Python 3.10 or later and [git](https://git-scm.com/downloads).
 
-On GitHub, click **Use this template** → **Create a new repository**. See GitHub's [guide to creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
+## 1. Create the project
 
-## 2. Rename the package
+::::{tab-set}
 
-The template's package is called `placeholder`. Rename it everywhere:
+:::{tab-item} uv
 
-- the `placeholder/` folder;
-- `pyproject.toml`: `name` (the name people `pip install`), `packages`, and the `version` line under `[tool.setuptools.dynamic]`;
-- `placeholder/__init__.py` and `tests/test_version.py`, which import it.
+```bash
+uvx --from git+https://github.com/SCENE-Collaboration/CodeAndDocsTemplate scene-repo-template new my-project
+```
 
-Then update the links to this repository: `urls` in `pyproject.toml`, and `github` and `title` in `docs/myst.yml`.
+`uvx` runs the generator without installing it. See [installing uv](https://docs.astral.sh/uv/getting-started/installation/).
+:::
 
-## 3. Choose a license
+:::{tab-item} pip
+In any Python environment:
+
+```bash
+pip install git+https://github.com/SCENE-Collaboration/CodeAndDocsTemplate
+scene-repo-template new my-project
+```
+
+:::
+
+:::{tab-item} conda
+The generator is installed with pip, into a conda environment of its own:
+
+```bash
+conda create -n scene-tools python pip
+conda activate scene-tools
+pip install git+https://github.com/SCENE-Collaboration/CodeAndDocsTemplate
+scene-repo-template new my-project
+```
+
+:::
+
+::::
+
+You will need to enter:
+- The distribution name (for `pip install`)
+- The import name
+- The project title
+- A one-line description
+- The author
+- The GitHub URL
+
+This will show a summary, and wait for confirmation.
+
+```{note}
+Use `--dry-run` for a preview.
+```
+
+
+The project then contains:
+
+- `pyproject.toml`, the package folder and a first test example in `tests/`;
+- `.pre-commit-config.yaml` and three GitHub Actions workflows: lint, tests and docs;
+- `docs/`, a Jupyter Book with SCENE's logo, colours and footer;
+- `LICENSE` (Apache-2.0) and a short `README.md`.
+
+## 2. Set up your environment
+
+In the new project, with your preferred package manager:
 
-`LICENSE` and the `license` field in `pyproject.toml` must name the same license. The template uses Apache-2.0; if you change it, change both.
+::::{tab-set}
 
-## 4. Set up your environment
+:::{tab-item} uv
 
 ```bash
-uv sync --extra dev        # or: pip install -e ".[dev]"
+cd my-project
+git init
+uv sync --extra dev
+uv run pre-commit install
+uv run pytest
+```
+
+:::
+
+:::{tab-item} pip
+
+```bash
+cd my-project
+git init
+python3 -m venv .venv          # Windows: py -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
 pre-commit install
-pre-commit run --all-files
+pytest
 ```
 
-*Code Formatting & Linting* in the [Guidelines](guidelines.md) explains what the hooks do.
+On Ubuntu and Debian, `python3 -m venv` needs the `python3-venv` package (`sudo apt install python3-venv`).
 
-## 5. Add your dependencies
+:::
 
-List them under `dependencies` in `pyproject.toml`, then run `uv lock` and commit `uv.lock` with the change. The `uv-lock` hook does this for you on commit.
+:::{tab-item} conda
 
-## 6. Turn on CI and the docs site
+```bash
+cd my-project
+git init
+conda create -n my-project python pip
+conda activate my-project
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+Install packages that only exist on conda (or that you prefer from conda-forge) with `conda install`, before `pip install -e`.
+:::
 
-- CI runs as soon as you push, but only if the repository is public: see *Continuous Integration* in the [Guidelines](guidelines.md).
-- To publish this book, enable GitHub Pages once: see [Documentation with Jupyter Book](jupyter-book.md#publish).
+::::
 
-## 7. Remove what you do not need
+`pip install -e` installs the package in editable mode: changes to its code take effect without reinstalling.
+See *Code Formatting & Linting* in the [Project standards](guidelines.md) for an explanation of the hooks.
+
+## 3. Choose a license
 
-Delete `docs/contributed-examples/` or the docs workflow (`.github/workflows/docs.yml`) if your project has no use for them, and replace the README with your own.
+Projects start with Apache-2.0.
+To change it, replace `LICENSE` and update every place that names the license:
+
+- the `license` field in `pyproject.toml`;
+- the *License* section of `README.md`;
+- `license` in `docs/myst.yml`.
+
+## 4. Add your dependencies
+
+List them under `dependencies` in `pyproject.toml`, then reinstall (`uv sync --extra dev`, or `pip install -e ".[dev]"`).
+
+The `uv-lock` pre-commit hook writes `uv.lock` on every commit that changes `pyproject.toml`, also for pip and conda users.
+Commit `uv.lock` with the change.
+
+```{note}
+`uv.lock` covers only `pyproject.toml`: record conda-only packages in a separate lockfile, see *Lockfiles* in the [Project standards](guidelines.md).
+```
+
+## 5. Turn on CI and the docs site
+
+- Create the repository on GitHub at the URL you decided, then commit and push.
+- CI runs as soon as you push, if the repository is public and Actions is enabled (**Settings → Actions**): see *Continuous Integration* in the [Project standards](guidelines.md).
+- To publish the docs, enable GitHub Pages once: see [Documentation with Jupyter Book](jupyter-book.md#publish).
+
+```{important}
+No docs needed? Delete `docs/` and `.github/workflows/docs.yml`.
+```

docs/index.md

@@ -2,7 +2,7 @@
 title: SCENE Code & Data Guidelines
 ---
 
-```{image} images/scene-logo.png
+```{image} ../src/scene_repo_template/skeleton/jupyter-book/docs/images/scene-logo.png
 :alt: SCENE logo
 :width: 140px
 :align: center

docs/myst.yml

@@ -26,9 +26,9 @@ project:
 site:
   template: book-theme
   options:
-    logo: images/scene-logo.png
+    logo: ../src/scene_repo_template/skeleton/jupyter-book/docs/images/scene-logo.png
     logo_text: SCENE
-    favicon: images/favicon.png
-    style: _static/scene.css
+    favicon: ../src/scene_repo_template/skeleton/jupyter-book/docs/images/favicon.png
+    style: ../src/scene_repo_template/skeleton/jupyter-book/docs/_static/scene.css
   parts:
-    primary_sidebar_footer: _static/footer.md
+    primary_sidebar_footer: ../src/scene_repo_template/skeleton/jupyter-book/docs/_static/footer.md

pyproject.toml

@@ -3,8 +3,8 @@ build-backend = "setuptools.build_meta"
 requires = [ "setuptools>=77" ]
 
 [project]
-name = "SCENE-placeholder" # Please update
-description = "A SCENE collaboration package for..."
+name = "scene-repo-template"
+description = "Create SCENE code projects: packaging, tests, CI and documentation already set up."
 readme = "README.md"
 license = "Apache-2.0" # keep in line with LICENSE
 license-files = [ "LICENSE" ]
@@ -17,18 +17,21 @@ classifiers = [
   "Topic :: Scientific/Engineering",
 ]
 dynamic = [ "version" ]
-dependencies = []
+dependencies = [ "questionary>=2" ]
 
 optional-dependencies.dev = [ "pre-commit", "pytest", "pytest-cov" ]
 optional-dependencies.docs = [ "jupyter-book>=2" ]
+scripts.scene-repo-template = "scene_repo_template.cli:main"
 urls."Bug Tracker" = "https://github.com/SCENE-Collaboration/CodeAndDocsTemplate/issues"
 urls.Source = "https://github.com/SCENE-Collaboration/CodeAndDocsTemplate"
 
 [tool.setuptools]
-packages = [ "placeholder" ]
+packages.find.where = [ "src" ]
+# The project skeleton ships as data: generated projects are copied from it.
+package-data.scene_repo_template = [ "skeleton/**/*" ]
 
 [tool.setuptools.dynamic]
-version = { attr = "placeholder.version.__version__" }
+version = { attr = "scene_repo_template.version.__version__" }
 
 [tool.pytest.ini_options]
 testpaths = [ "tests" ]

src/scene_repo_template/__init__.py

@@ -0,0 +1,3 @@
+from scene_repo_template.version import __version__
+
+__all__ = ["__version__"]