diff --git a/.copier-answers.yaml b/.copier-answers.yaml index c3e0e9f..067feb6 100644 --- 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: cpp +add_wiki: true email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates project_description: A C++-Python project template diff --git a/.github/workflows/wiki.yaml b/.github/workflows/wiki.yaml new file mode 100644 index 0000000..1588acd --- /dev/null +++ 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/Makefile b/Makefile index 0ce65be..da779c4 100644 --- a/Makefile +++ b/Makefile @@ -24,7 +24,7 @@ install: ## install python library ######### # LINTS # ######### -.PHONY: lint-py lint-cpp lint lints +.PHONY: lint-py lint-cpp lint-docs lint lints lint-py: ## run python linter with ruff python -m ruff check python_template_cpp python -m ruff format --check python_template_cpp @@ -32,6 +32,10 @@ lint-py: ## run python linter with ruff lint-cpp: ## run cpp linter clang-format --dry-run -Werror -i -style=file `find ./cpp -name "*.*pp"` +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-cpp lint-py ## run project linters # alias @@ -45,7 +49,11 @@ fix-py: ## fix python formatting with ruff fix-cpp: ## fix cpp formatting clang-format -i -style=file `find ./cpp -name "*.*pp"` -fix: fix-cpp 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-cpp fix-py fix-docs ## run project autoformatters # alias format: fix diff --git a/README.md b/README.md index 5af0113..b769c1f 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,5 @@ A C++-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 new file mode 100644 index 0000000..406e4f6 --- /dev/null +++ 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-cpp/tree/main/docs/wiki)._ diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,16 @@ + + +**[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 new file mode 100644 index 0000000..86147b7 --- /dev/null +++ b/docs/wiki/contribute/Build-from-Source.md @@ -0,0 +1,103 @@ +`python-template-cpp` is written in Python. While prebuilt wheels are provided for end users, it is also straightforward to build `python-template-cpp` 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-cpp` 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-cpp` 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-cpp.git +cd python-template-cpp +``` + +## 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-cpp` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`python-template-cpp` has extensive Python tests. The tests can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test +``` diff --git a/docs/wiki/contribute/Contribute.md b/docs/wiki/contribute/Contribute.md new file mode 100644 index 0000000..09df960 --- /dev/null +++ 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-cpp/blob/main/LICENSE). + +> [!NOTE] +> +> `python-template-cpp` 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-cpp/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/python-project-templates/python-template-cpp/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 new file mode 100644 index 0000000..f3be2c0 --- /dev/null +++ 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-cpp`, 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-cpp` from a `git` clone, you will also need to +configure `git` and your GitHub account for `python-template-cpp` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `python-template-cpp`. To do so, click +the "fork" button at https://github.com/python-project-templates/python-template-cpp, or just navigate +[here](https://github.com/python-project-templates/python-template-cpp/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 index 19c59fa..fa20de5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,8 +37,11 @@ develop = [ "bump-my-version", "check-manifest", "cibuildwheel", + "codespell>=2.4,<2.5", "hatch-cpp", "hatchling", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "pytest", "pytest-cov", "ruff", @@ -56,6 +59,7 @@ Homepage = "https://github.com/python-project-templates/python-template-cpp" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "python_template_cpp/__init__.py"