diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 50c6e2d1..094dc63a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,7 +1,7 @@ repos: # Hooks that are run everywhere - - repo: https://github.com/pre-commit/mirrors-prettier - rev: v4.0.0-alpha.8 # Only update together with the pre-commit yaml in the tempalate! + - repo: https://github.com/rbubley/mirrors-prettier + rev: v3.4.2 # Only update together with the pre-commit yaml in the tempalate! hooks: - id: prettier # Hooks that are run for scripts diff --git a/README.md b/README.md index 14d4b0c8..3f382a0c 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ Ecosystem packages are independent software libraries that interact with scverse Please check out the -- [example repo](https://github.com/scverse/cookiecutter-scverse-instance) and the -- [example documentation](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/) +- [example repo](https://github.com/scverse/cookiecutter-scverse-instance) and the +- [example documentation](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/) that are automatically generated and kept in sync with this template. @@ -32,14 +32,14 @@ Please consider making a tax-deductible [donation](https://numfocus.org/donate-t ## Features -- automated testing with [pytest][] -- continuous integration using GitHub actions. -- documentation hosted by [readthedocs][] -- coverage tests with [codecov][] -- [pre-commit][] checks for code style and consistency -- tutorials with [myst-nb][] and jupyter notebooks -- issue templates for better bug reports and feature requests -- [bump2version][] for managing releases +- automated testing with [pytest][] +- continuous integration using GitHub actions. +- documentation hosted by [readthedocs][] +- coverage tests with [codecov][] +- [pre-commit][] checks for code style and consistency +- tutorials with [myst-nb][] and jupyter notebooks +- issue templates for better bug reports and feature requests +- [bump2version][] for managing releases ## Getting started @@ -90,9 +90,9 @@ Further instructions on using this template can be found in the [dev docs includ We expect developers of scverse ecosystem packages to -- [write unit tests][write-tests] -- [provide documentation][write-docs], including tutorials where applicable -- support users through github and the [scverse discourse][] +- [write unit tests][write-tests] +- [provide documentation][write-docs], including tutorials where applicable +- support users through github and the [scverse discourse][] ## Changelog diff --git a/{{cookiecutter.project_name}}/.pre-commit-config.yaml b/{{cookiecutter.project_name}}/.pre-commit-config.yaml index 7f762b13..22a64f4a 100644 --- a/{{cookiecutter.project_name}}/.pre-commit-config.yaml +++ b/{{cookiecutter.project_name}}/.pre-commit-config.yaml @@ -6,8 +6,8 @@ default_stages: - pre-push minimum_pre_commit_version: 2.16.0 repos: - - repo: https://github.com/pre-commit/mirrors-prettier - rev: v4.0.0-alpha.8 + - repo: https://github.com/rbubley/mirrors-prettier + rev: v3.4.2 hooks: - id: prettier - repo: https://github.com/tox-dev/pyproject-fmt diff --git a/{{cookiecutter.project_name}}/CHANGELOG.md b/{{cookiecutter.project_name}}/CHANGELOG.md index e7b78085..c1856287 100644 --- a/{{cookiecutter.project_name}}/CHANGELOG.md +++ b/{{cookiecutter.project_name}}/CHANGELOG.md @@ -12,4 +12,4 @@ and this project adheres to [Semantic Versioning][]. ### Added -- Basic tool, preprocessing and plotting functions +- Basic tool, preprocessing and plotting functions diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index f5393aab..77f9d4f1 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -158,11 +158,11 @@ This will automatically create a git tag and trigger a Github workflow that crea Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: -- The [myst][] extension allows to write documentation in markdown/Markedly Structured Text -- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). -- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) -- [sphinx-autodoc-typehints][], to automatically reference annotated input and output types -- Citations (like {cite:p}`Virshup_2023`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) +- The [myst][] extension allows to write documentation in markdown/Markedly Structured Text +- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). +- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) +- [sphinx-autodoc-typehints][], to automatically reference annotated input and output types +- Citations (like {cite:p}`Virshup_2023`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) See scanpy’s {doc}`scanpy:dev/documentation` for more information on how to write your own. @@ -186,10 +186,10 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu #### Hints -- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. - Only if you do so can sphinx automatically create a link to the external documentation. -- If building the documentation fails because of a missing link that is outside your control, - you can add an entry to the `nitpick_ignore` list in `docs/conf.py` +- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. + Only if you do so can sphinx automatically create a link to the external documentation. +- If building the documentation fails because of a missing link that is outside your control, + you can add an entry to the `nitpick_ignore` list in `docs/conf.py` (docs-building)= diff --git a/{{cookiecutter.project_name}}/docs/template_usage.md b/{{cookiecutter.project_name}}/docs/template_usage.md index 85fedc66..daa317e2 100644 --- a/{{cookiecutter.project_name}}/docs/template_usage.md +++ b/{{cookiecutter.project_name}}/docs/template_usage.md @@ -169,13 +169,13 @@ We recommend using [readthedocs.org][] (RTD) to build and host the documentation To enable readthedocs, head over to [their website][readthedocs.org] and sign in with your GitHub account. On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository. -- Make sure to choose the correct name of the default branch. - On GitHub, the name of the default branch should be `main` (it has recently changed from `master` to `main`). -- We recommend enabling documentation builds for pull requests (PRs). - This ensures that a PR doesn't introduce changes that break the documentation. - To do so, got to `Admin -> Advanced Settings`, check the `Build pull requests for this projects` option, and click `Save`. - For more information, please refer to the [official RTD documentation][rtd-prs]. -- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. +- Make sure to choose the correct name of the default branch. + On GitHub, the name of the default branch should be `main` (it has recently changed from `master` to `main`). +- We recommend enabling documentation builds for pull requests (PRs). + This ensures that a PR doesn't introduce changes that break the documentation. + To do so, got to `Admin -> Advanced Settings`, check the `Build pull requests for this projects` option, and click `Save`. + For more information, please refer to the [official RTD documentation][rtd-prs]. +- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. If your project is private, there are ways to enable docs rendering on [readthedocs.org][] but it is more cumbersome and requires a different subscription for read the docs. See a guide [here](https://docs.readthedocs.io/en/stable/guides/importing-private-repositories.html). @@ -260,44 +260,44 @@ Once authorized, pre-commit.ci should automatically be activated. The following pre-commit hooks are for code style and format: -- [prettier](https://prettier.io/docs/en/index.html): - standard code formatter for non-Python files (e.g. YAML). -- [ruff][] formatting (`ruff-format`) -- [ruff][] based checks: - - [isort](https://beta.ruff.rs/docs/rules/#isort-i) (rule category: `I`): - sort module imports into sections and types. - - [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (rule category: `D`): - pydocstyle extension of flake8. - - [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (rule category: `TID`): - tidy module imports. - - [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (rule category: `C4`): - write better list/set/dict comprehensions. - - [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (rule category: `UP`): - upgrade syntax for newer versions of the language. +- [prettier](https://prettier.io/docs/en/index.html): + standard code formatter for non-Python files (e.g. YAML). +- [ruff][] formatting (`ruff-format`) +- [ruff][] based checks: + - [isort](https://beta.ruff.rs/docs/rules/#isort-i) (rule category: `I`): + sort module imports into sections and types. + - [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (rule category: `D`): + pydocstyle extension of flake8. + - [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (rule category: `TID`): + tidy module imports. + - [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (rule category: `C4`): + write better list/set/dict comprehensions. + - [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (rule category: `UP`): + upgrade syntax for newer versions of the language. The following pre-commit hooks are for errors and inconsistencies: -- [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks for text files. - - **detect-private-key**: checks for the existence of private keys. - - **check-ast**: check whether files parse as valid python. - - **end-of-file-fixer**: check files end in a newline and only a newline. - - **mixed-line-ending**: checks mixed line ending. - - **trailing-whitespace**: trims trailing whitespace. - - **check-case-conflict**: check files that would conflict with case-insensitive file systems. - - **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. - These files are created by the [automated template sync](#automated-template-sync) - if there's a merge conflict and need to be addressed manually. -- [ruff][] based checks: - - [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (rule category: `F`): - various checks for errors. - - [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (rule category: `E`, `W`): - various checks for errors. - - [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (rule category: `B`): - find possible bugs and design issues in program. - - [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (rule category: `BLE`): - checks for blind, catch-all `except` statements. - - [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (rule category: `RUF`): - - `RUF100`: remove unneccesary `# noqa` comments () +- [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks for text files. + - **detect-private-key**: checks for the existence of private keys. + - **check-ast**: check whether files parse as valid python. + - **end-of-file-fixer**: check files end in a newline and only a newline. + - **mixed-line-ending**: checks mixed line ending. + - **trailing-whitespace**: trims trailing whitespace. + - **check-case-conflict**: check files that would conflict with case-insensitive file systems. + - **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. + These files are created by the [automated template sync](#automated-template-sync) + if there's a merge conflict and need to be addressed manually. +- [ruff][] based checks: + - [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (rule category: `F`): + various checks for errors. + - [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (rule category: `E`, `W`): + various checks for errors. + - [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (rule category: `B`): + find possible bugs and design issues in program. + - [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (rule category: `BLE`): + checks for blind, catch-all `except` statements. + - [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (rule category: `RUF`): + - `RUF100`: remove unneccesary `# noqa` comments () #### How to add or remove pre-commit checks @@ -374,9 +374,9 @@ add it to Ruff’s [`external = [...]`][ruff-external] setting to prevent `RUF10 Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] data structures and typically use an API as originally [introduced by scanpy][scanpy-api] with the following submodules: -- `pp` for preprocessing -- `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting function) -- `pl` for plotting functions +- `pp` for preprocessing +- `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting function) +- `pl` for plotting functions You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, @@ -440,12 +440,12 @@ The pull request can only be merged after all `*.rej` files have been removed. :::{tip} The following hints may be useful to work with the template sync: -- GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days. - You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository. -- If you want to ignore certain files from the template update, - you can add them to the `[tool.cruft]` section in the `pyproject.toml` file in the root of your repository. - More details are described in the [cruft documentation][cruft-update-project]. -- To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`. +- GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days. + You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository. +- If you want to ignore certain files from the template update, + you can add them to the `[tool.cruft]` section in the `pyproject.toml` file in the root of your repository. + More details are described in the [cruft documentation][cruft-update-project]. +- To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`. :::