python-project-templates · timkpaine · Jul 29, 2025 · Jul 29, 2025
diff --git a/.copier-answers.yaml b/.copier-answers.yaml
@@ -1,9 +1,9 @@
 # Changes here will be overwritten by Copier
-_commit: c53b04c
+_commit: e29838a
 _src_path: https://github.com/python-project-templates/base.git
 add_docs: true
-add_wiki: true
 add_extension: js
+add_wiki: true
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
 project_description: A JavaScript-Python project template

diff --git a/.github/workflows/wiki.yaml b/.github/workflows/wiki.yaml
@@ -0,0 +1,27 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "README.md"
+  workflow_dispatch:
+
+concurrency:
+  group: docs
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: cp README.md docs/wiki/Home.md
+      - uses: Andrew-Chen-Wang/github-wiki-action@v4
+        with:
+          path: docs/wiki
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "eslint.workingDirectories": ["./js"]
+}
diff --git a/Makefile b/Makefile
@@ -34,20 +34,28 @@ lint-py:  ## run python linter with ruff
 lint-js:  ## run js linter
 	cd js; pnpm lint
 
-lint: lint-js lint-py  ## run project linters
+lint-docs:  ## lint docs with mdformat and codespell
+	python -m mdformat --check README.md docs/wiki/
+	python -m codespell_lib README.md docs/wiki/
+
+lint: lint-js lint-py lint-docs  ## run project linters
 
 # alias
 lints: lint
 
-.PHONY: fix-py fix-js fix format
+.PHONY: fix-py fix-js fix-docs fix format
 fix-py:  ## fix python formatting with ruff
 	python -m ruff check --fix python_template_js
 	python -m ruff format python_template_js
 
 fix-js:  ## fix js formatting
 	cd js; pnpm fix
 
-fix: fix-js fix-py  ## run project autoformatters
+fix-docs:  ## autoformat docs with mdformat and codespell
+	python -m mdformat README.md docs/wiki/
+	python -m codespell_lib --write README.md docs/wiki/
+
+fix: fix-js fix-py fix-docs  ## run project autoformatters
 
 # alias
 format: fix

diff --git a/README.md b/README.md
@@ -9,6 +9,5 @@ A JavaScript-Python project template
 
 ## Overview
 
-
 > [!NOTE]
 > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
diff --git a/docs/wiki/_Footer.md b/docs/wiki/_Footer.md
@@ -0,0 +1 @@
+_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/python-project-templates/python-template-js/tree/main/docs/wiki)._
diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md
@@ -0,0 +1,16 @@
+<!--
+This sidebar is displayed on the GitHub Wiki section instead of the default sidebar.
+Notes for editors:
+- Ensure links don't have the file extensions (i.e., `.md`)
+- Do not use colons (':') in page titles, they don't render properly as links in the sidebar
+- Use only the filenames in this page (without the filepath and file extension)
+-->
+
+**[Home](Home)**
+
+**Get Started**
+
+- [Installation](Installation)
+- [Contributing](Contribute)
+- [Development Setup](Local-Development-Setup)
+- [Build from Source](Build-from-Source)
diff --git a/docs/wiki/contribute/Build-from-Source.md b/docs/wiki/contribute/Build-from-Source.md
@@ -0,0 +1,131 @@
+`python-template-js` is written in Python and JavaScript. While prebuilt wheels are provided for end users, it is also straightforward to build `python-template-js` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository.
+
+- [Make commands](#make-commands)
+- [Prerequisites](#prerequisites)
+- [Clone](#clone)
+- [Install Python dependencies](#install-python-dependencies)
+- [Build](#build)
+- [Lint and Autoformat](#lint-and-autoformat)
+- [Testing](#testing)
+
+## Make commands
+
+As a convenience, `python-template-js` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments
+
+```bash
+> make
+
+build                          build the library
+clean                          clean the repository
+fix                            run autofixers
+install                        install library
+lint                           run lints
+test                           run the tests
+```
+
+## Prerequisites
+
+`python-template-js` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine.
+
+## Clone
+
+Clone the repo with:
+
+```bash
+git clone https://github.com/python-project-templates/python-template-js.git
+cd python-template-js
+```
+
+## Install NodeJS
+
+Follow the instructions for [installing NodeJS](https://nodejs.org/en/download/package-manager/all) for your system. Once installed, you can [install `pnpm`](https://pnpm.io/installation) with:
+
+```bash
+npm install --global pnpm
+```
+
+## Install Python dependencies
+
+Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them:
+
+```bash
+make requirements
+```
+
+Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/).
+
+## Build
+
+Build the python project in the usual manner:
+
+```bash
+make build
+```
+
+## Lint and Autoformat
+
+`python-template-js` has linting and auto formatting.
+
+| Language   | Linter      | Autoformatter | Description |
+| :--------- | :---------- | :------------ | :---------- |
+| Python     | `ruff`      | `ruff`        | Style       |
+| Python     | `ruff`      | `ruff`        | Imports     |
+| JavaScript | `prettier`  | `prettier`    | Style       |
+| Markdown   | `mdformat`  | `mdformat`    | Style       |
+| Markdown   | `codespell` |               | Spelling    |
+
+**Python Linting**
+
+```bash
+make lint-py
+```
+
+**Python Autoformatting**
+
+```bash
+make fix-py
+```
+
+**JavaScript Linting**
+
+```bash
+make lint-js
+```
+
+**JavaScript Autoformatting**
+
+```bash
+make fix-js
+```
+
+**Documentation Linting**
+
+```bash
+make lint-docs
+```
+
+**Documentation Autoformatting**
+
+```bash
+make fix-docs
+```
+
+## Testing
+
+`python-template-js` has both Python and JavaScript tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with
+
+```bash
+make develop
+```
+
+**Python**
+
+```bash
+make test-py
+```
+
+**JavaScript**
+
+```bash
+make test-js
+```
diff --git a/docs/wiki/contribute/Contribute.md b/docs/wiki/contribute/Contribute.md
@@ -0,0 +1,15 @@
+Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/python-project-templates/python-template-js/blob/main/LICENSE).
+
+> [!NOTE]
+>
+> `python-template-js` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions.
+> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed".
+> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing).
+
+For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/python-project-templates/python-template-js/issues).
+
+For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/python-project-templates/python-template-js/discussions).
+
+For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start.
+
+For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten.
diff --git a/docs/wiki/contribute/Local-Development-Setup.md b/docs/wiki/contribute/Local-Development-Setup.md
@@ -0,0 +1,55 @@
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Step 1: Build from Source](#step-1-build-from-source)
+- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development)
+  - [Create your fork](#create-your-fork)
+  - [Configure remotes](#configure-remotes)
+  - [Authenticating with GitHub](#authenticating-with-github)
+- [Guidelines](#guidelines)
+
+## Step 1: Build from Source
+
+To work on `python-template-js`, you are going to need to build it from source. See
+[Build from Source](Build-from-Source) for
+detailed build instructions.
+
+Once you've built `python-template-js` from a `git` clone, you will also need to
+configure `git` and your GitHub account for `python-template-js` development.
+
+## Step 2: Configuring Git and GitHub for Development
+
+### Create your fork
+
+The first step is to create a personal fork of `python-template-js`. To do so, click
+the "fork" button at https://github.com/python-project-templates/python-template-js, or just navigate
+[here](https://github.com/python-project-templates/python-template-js/fork) in your browser. Set the
+owner of the repository to your personal GitHub account if it is not
+already set that way and click "Create fork".
+
+### Configure remotes
+
+Next, you should set some names for the `git` remotes corresponding to
+main python-project-templates repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information.
+
+### Authenticating with GitHub
+
+If you have not already configured `ssh` access to GitHub, you can find
+instructions to do so
+[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh),
+including instructions to create an SSH key if you have not done
+so. Authenticating with SSH is usually the easiest route. If you are working in
+an environment that does not allow SSH connections to GitHub, you can look into
+[configuring a hardware
+passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys)
+or adding a [personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+to avoid the need to type in your password every time you push to your fork.
+
+## Guidelines
+
+After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions.
+
+If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release.
+
+Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed.
diff --git a/pyproject.toml b/pyproject.toml
@@ -35,8 +35,11 @@ develop = [
     "build",
     "bump-my-version",
     "check-manifest",
+    "codespell>=2.4,<2.5",
     "hatch-jupyter-builder",
     "hatchling",
+    "mdformat>=0.7.22,<0.8",
+    "mdformat-tables>=1",
     "pytest",
     "pytest-cov",
     "ruff",
@@ -54,6 +57,7 @@ Homepage = "https://github.com/python-project-templates/python-template-js"
 current_version = "0.1.0"
 commit = true
 tag = true
+commit_args = "-s"
 
 [[tool.bumpversion.files]]
 filename = "python_template_js/__init__.py"
@@ -75,6 +79,7 @@ ignore = [
     ".copier-answers.yaml",
     "js/pnpm-lock.yaml",
     "Makefile",
+    ".vscode/*",
     "python_template_js/extension/**/*",
     "docs/**/*",
     "js/dist/**/*",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,6 +9,5 @@ A JavaScript-Python project template

		## Overview


		> [!NOTE]
		> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/python-project-templates/python-template-js/tree/main/docs/wiki)._