diff --git a/README.md b/README.md index ff88a784..ec98a601 100644 --- a/README.md +++ b/README.md @@ -5,23 +5,23 @@ Spend less time setting up and configuring your new Python packages and comply w Use this [Copier](https://copier.readthedocs.io) template to generate an empty Python package. Features include: - Boilerplate unit tests and documentation, -- [Python static setup configuration]({{directory_name}}/pyproject.toml), +- [Python static setup configuration](template/pyproject.toml), - Open source software license, -- Continuous integration with [GitHub action workflows]({{directory_name}}/.github/workflows) for building, testing, link checking and linting, +- Continuous integration with [GitHub action workflows](template/.github/workflows) for building, testing, link checking and linting, - Code style checking with [ruff](https://beta.ruff.rs/), -- [Editorconfig]({{directory_name}}/.editorconfig), +- [Editorconfig](template/.editorconfig), - Usage and contribution documents: - - [README.md]({{directory_name}}/README.md) for package users, - - [README.dev.md]({{directory_name}}/README.dev.md) for package developer, - - [project_setup.md]({{directory_name}}/project_setup.md) with extensive documentation about project setup, - - [Change log]({{directory_name}}/CHANGELOG.md), - - [Code of Conduct]({{directory_name}}/CODE_OF_CONDUCT.md), - - [Contributing guidelines]({{directory_name}}/CONTRIBUTING.md), + - [README.md](template/README.md) for package users, + - [README.dev.md](template/README.dev.md) for package developer, + - [project_setup.md](template/project_setup.md) with extensive documentation about project setup, + - [Change log](template/CHANGELOG.md), + - [Code of Conduct](template/CODE_OF_CONDUCT.md), + - [Contributing guidelines](template/CONTRIBUTING.md), - Continuous code quality and code coverage reporting using [Sonarcloud](https://sonarcloud.io/), -- Automatic creation of [issues]({{directory_name}}/.github/next_steps) with instructions how to pass all GitHub action workflows and integrate with services like Zenodo and Read the Docs, -- Instructions how to make package [citable]({{directory_name}}/.github/next_steps/02_citation.md) +- Automatic creation of [issues](template/.github/next_steps) with instructions how to pass all GitHub action workflows and integrate with services like Zenodo and Read the Docs, +- Instructions how to make package [citable](template/.github/next_steps/02_citation.md) - FAIR software recommendation badge, -- Optional [pre commit hook]({{directory_name}}/README.dev.md#running-linters-locally) to catch lint errors early +- Optional [pre commit hook](template/README.dev.md#running-linters-locally) to catch lint errors early ## Badges @@ -61,8 +61,7 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination | Name | Default value | Explanation | | ------------------------- | ------------- | ----------- | -| directory_name | my-python-project | Name of the directory that contains the package. Avoid using spaces or uppercase letters for the best experience across operating systems. To get an impression of what will be generated, see the directory tree [below](https://github.com/NLeSC/python-template#step-33-read-about-what-was-just-generated) | -| package_name | my_python_package | Name of the package. Avoid using spaces, dashes, or uppercase letters for the best experience across operating systems. | +| package_name | my_python_package | Name of the package. Avoid using spaces, dashes, or uppercase letters for the best experience across operating systems. This also will be used as the github repository name.| | package_short_description | Short description of package | The information that you enter here will end up in the README, documentation, license, and pyproject.toml, so it may be a good idea to prepare something in advance. | | keyword1 | keyword1 | A term that describes your package. | | keyword2 | keyword2 | Another term that describes your package. | @@ -75,7 +74,7 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination | code_of_conduct_email | yourname@esciencecenter.nl | Email address of the person who should be contacted in case of violations of the Code of Conduct. | Once the project files have been generated, follow the steps outlined in -[{{directory_name}}/next_steps.md]({{directory_name}}/next_steps.md). +[template/next_steps.md](template/next_steps.md). ### Step 3/3: Read about what was just generated @@ -135,7 +134,7 @@ Good job! You have now generated the skeleton for your package: └── .zenodo.json ``` -For an explanation of what's there, read on in the [project_setup.md]({{directory_name}}/project_setup.md) file. +For an explanation of what's there, read on in the [project_setup.md](template/project_setup.md) file. There are also instructions on how to [apply the template to an existing Python package](ADD_TO_EXISTING_PACKAGE.md). ## Examples diff --git a/copier.yml b/copier.yml index 77fc3fd3..8359c1f1 100644 --- a/copier.yml +++ b/copier.yml @@ -11,10 +11,10 @@ package_name: package_short_description: type: str default: Short description of package - # validator: >- - # {% if '"' in package_short_description %} - # package_short_description must not contain unescaped double quotes. Use \\" for double quotes. - # {% endif %} + validator: >- + {% if (package_short_description | regex_replace ('"', '\\\\"')|regex_replace ("'", "\\\\'")%} + package_short_description must not contain unescaped double or single quotes. + {% endif %} keyword1: type: str default: keyword1 @@ -59,11 +59,11 @@ code_of_conduct_email: _subdirectory: template repository: - default: git@github.com:{{ github_organization }}/{{ directory_name }} + default: git@github.com:{{ github_organization }}/{{ package_name }} when: false repository_url: - default: https://github.com/{{ github_organization }}/{{ directory_name }} + default: https://github.com/{{ github_organization }}/{{ package_name }} when: false diff --git a/setup.cfg b/setup.cfg index b6b2cb16..d52e15ba 100644 --- a/setup.cfg +++ b/setup.cfg @@ -51,4 +51,4 @@ dev = [tool:pytest] testpaths = tests -norecursedirs = .git .github hooks {{directory_name}} +norecursedirs = .git .github hooks template diff --git a/template/.github/next_steps/01_sonarcloud_integration.md.jinja b/template/.github/next_steps/01_sonarcloud_integration.md.jinja index 152edb6b..bcc69ce0 100644 --- a/template/.github/next_steps/01_sonarcloud_integration.md.jinja +++ b/template/.github/next_steps/01_sonarcloud_integration.md.jinja @@ -10,7 +10,7 @@ In order to configure Sonarcloud analysis [GitHub Action workflow]({{repository_ 1. login with your GitHub account 1. add Sonarcloud organization or reuse existing one 1. set up a repository -1. go to [new code definition administration page](https://sonarcloud.io/project/new_code?id={{github_organization}}_{{directory_name}}) and select `Number of days` option +1. go to [new code definition administration page](https://sonarcloud.io/project/new_code?id={{github_organization}}_{{package_name}}) and select `Number of days` option 1. To be able to run the analysis: 1. a token must be created at [Sonarcloud account](https://sonarcloud.io/account/security/) - 1. the created token must be added as `SONAR_TOKEN` to [secrets on GitHub](https://github.com/{{github_organization}}/{{directory_name}}/settings/secrets/actions) + 1. the created token must be added as `SONAR_TOKEN` to [secrets on GitHub](https://github.com/{{github_organization}}/{{package_name}}/settings/secrets/actions) diff --git a/template/.github/next_steps/03_readthedocs.md.jinja b/template/.github/next_steps/03_readthedocs.md.jinja index 5c7917d0..5648c020 100644 --- a/template/.github/next_steps/03_readthedocs.md.jinja +++ b/template/.github/next_steps/03_readthedocs.md.jinja @@ -9,12 +9,12 @@ To host the documentation of this repository please perform the following instru 1. go to [Read the Docs](https://readthedocs.org/dashboard/import/?) 1. log in with your GitHub account -1. find `{{ github_organization }}/{{ directory_name }}` in list and press `+` button. +1. find `{{ github_organization }}/{{ package_name }}` in list and press `+` button. * If repository is not listed, 1. go to [Read the Docs GitHub app](https://github.com/settings/connections/applications/fae83c942bc1d89609e2) 2. make sure {{ github_organization }} has been granted access. 3. reload repository list on Read the Docs import page -1. wait for the first build to be completed at +1. wait for the first build to be completed at 1. check that the link of the documentation badge in the [README.md]({{ repository_url }}) works See [README.dev.md#]({{repository_url}}/blob/main/README.dev.md#generating-the-api-docs) how to build documentation site locally. diff --git a/template/README.md.jinja b/template/README.md.jinja index 4ffb4ea4..8093442c 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -5,15 +5,15 @@ | fair-software.eu recommendations | | | :-- | :-- | | (1/5) code repository | [![github repo badge](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)]({{repository_url}}) | -| (2/5) license | [![github license badge](https://img.shields.io/github/license/{{github_organization}}/{{directory_name}})]({{repository_url}}) | +| (2/5) license | [![github license badge](https://img.shields.io/github/license/{{github_organization}}/{{package_name}})]({{repository_url}}) | | (3/5) community registry | [![RSD](https://img.shields.io/badge/rsd-{{package_name}}-00a3e3.svg)](https://www.research-software.nl/software/{{package_name}}) [![workflow pypi badge](https://img.shields.io/pypi/v/{{package_name}}.svg?colorB=blue)](https://pypi.python.org/project/{{package_name}}/) | | (4/5) citation | [![DOI](https://zenodo.org/badge/DOI/.svg)](https://doi.org/) | | (5/5) checklist | [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects//badge)](https://bestpractices.coreinfrastructure.org/projects/) | | howfairis | [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) | | **Other best practices** |   | -| Static analysis | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{directory_name}}&metric=alert_status)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{directory_name}}) | -| Coverage | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{directory_name}}&metric=coverage)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{directory_name}}) | -| Documentation | [![Documentation Status](https://readthedocs.org/projects/{{directory_name}}/badge/?version=latest)](https://{{directory_name}}.readthedocs.io/en/latest/?badge=latest) | +| Static analysis | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{package_name}}&metric=alert_status)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{package_name}}) | +| Coverage | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project={{github_organization}}_{{package_name}}&metric=coverage)](https://sonarcloud.io/dashboard?id={{github_organization}}_{{package_name}}) | +| Documentation | [![Documentation Status](https://readthedocs.org/projects/{{package_name}}/badge/?version=latest)](https://{{package_name}}.readthedocs.io/en/latest/?badge=latest) | | **GitHub Actions** |   | | Build | [![build]({{repository_url}}/actions/workflows/build.yml/badge.svg)]({{repository_url}}/actions/workflows/build.yml) | | Citation data consistency | [![cffconvert]({{repository_url}}/actions/workflows/cffconvert.yml/badge.svg)]({{repository_url}}/actions/workflows/cffconvert.yml) | @@ -32,7 +32,7 @@ To install {{ package_name }} from GitHub repository, do: ```console git clone {{ repository }}.git -cd {{ directory_name }} +cd {{ package_name }} python -m pip install . ``` diff --git a/template/next_steps.md.jinja b/template/next_steps.md.jinja index a44875d6..8d0aa499 100644 --- a/template/next_steps.md.jinja +++ b/template/next_steps.md.jinja @@ -13,8 +13,8 @@ Alternatively, you can also use a personal access token, see [Creating a personal access token](https://docs.github.com/en/github-ae@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). If you choose this option, below you will have to replace `git@github.com:` by `https://github.com/`. +Inside of the generated directory, run the following commands: ```shell -cd {{ directory_name }} git init git add --all git commit -m "first commit" @@ -26,7 +26,7 @@ git remote add origin {{ repository }} Go to [https://github.com/organizations/{{github_organization}}/repositories/new](https://github.com/organizations/{{github_organization}}/repositories/new) -and create a new repository named `{{ directory_name }}` as an empty repository, then push your commits to GitHub: +and create a new repository named `{{ package_name }}` as an empty repository, then push your commits to GitHub: ```shell git push --set-upstream origin main diff --git a/template/project_setup.md.jinja b/template/project_setup.md.jinja index ca065bf2..0f4949f2 100644 --- a/template/project_setup.md.jinja +++ b/template/project_setup.md.jinja @@ -76,7 +76,7 @@ help you decide which tool to use for packaging. ## Package version number - We recommend using [semantic versioning](https://guide.esciencecenter.nl/#/best_practices/releases?id=semantic-versioning). -- For convenience, the package version is stored in a single place: `{{ directory_name }}/pyproject.toml` under the `tool.bumpversion` header. +- For convenience, the package version is stored in a single place: `pyproject.toml` under the `tool.bumpversion` header. - Don't forget to update the version number before [making a release](https://guide.esciencecenter.nl/#/best_practices/releases)! ## Logging diff --git a/template/sonar-project.properties.jinja b/template/sonar-project.properties.jinja index 2455ef43..268e30d7 100644 --- a/template/sonar-project.properties.jinja +++ b/template/sonar-project.properties.jinja @@ -1,5 +1,5 @@ sonar.organization={{ github_organization }} -sonar.projectKey={{ github_organization }}_{{ directory_name }} +sonar.projectKey={{ github_organization }}_{{ package_name }} sonar.host.url=https://sonarcloud.io sonar.sources=src/{{ package_name }}/ sonar.tests=tests/ diff --git a/tests/test_values.py b/tests/test_values.py index 1f240323..f0cafd48 100644 --- a/tests/test_values.py +++ b/tests/test_values.py @@ -16,21 +16,3 @@ def test_single_quotes_in_name_and_description(copie): project = copie.copy(extra_answers=ctx) assert project.exit_code == 0 - - -def test_dash_in_directory_name(copie): - ctx = { - "directory_name": "my-python-project" - } - project = copie.copy(extra_answers=ctx) - - assert project.exit_code == 0 - - -def test_space_in_directory_name(copie): - ctx = { - "directory_name": "my python project" - } - project = copie.copy(extra_answers=ctx) - - assert project.exit_code == 0