From 3136fa824d0e4158434accf896ef31d57a8b5f96 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 10:44:17 +0100 Subject: [PATCH 01/20] add first-commit section --- .../docs/developer_docs.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index c37ee470..75324d5a 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -8,6 +8,62 @@ Welcome to the developer guidelines! This document is split into two parts: ## Setting up the repository +### First commit + +If you are reading this, you should have just completed the repository creation with : + +```bash +cruft create https://github.com/scverse/cookiecutter-scverse +``` + +and you should have + +``` +cd your-awesome-project +``` + +into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github. +You can follow the instructions directly on [github](https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui). +Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. +If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. + +Now that your new project repository has been created on github at `https://github.com/your-account/your-awesome-project` you can push your first commit to github. +To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: + +Assuming you are in `/your/path/to/your-awesome-project`. Add all files and commit. + +```bash +# stage all files of your new repo +git add --all +# commit +git commit -m "first commit" +``` + +You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](developer_docs.md#pre-commit-checks) in this document. + +```{note} +There is a chance that the `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the `.cruft.json` file. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again. E.g. with + +``` + +git add -u # add (or update) all tracked file +git commit -m "first commit" + +``` + +``` + +Now that all the files of the newly created project have been committed, go ahead with the remaining steps: + +```bash +# update the `origin` of your local repo with the remote github link +git remote add origin https://github.com/giovp/temp_repo.git +# rename the default branch to main +git branch -M main +# push all your files to remote +git push -u origin main +``` + ### Documentation on _readthedocs_ We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. From b0c32916cfeb18c811333f4ac184f7e08df2b658 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 10:49:12 +0100 Subject: [PATCH 02/20] updates --- {{cookiecutter.project_name}}/docs/developer_docs.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 75324d5a..ed357380 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -42,15 +42,7 @@ git commit -m "first commit" You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](developer_docs.md#pre-commit-checks) in this document. ```{note} -There is a chance that the `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the `.cruft.json` file. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again. E.g. with - -``` - -git add -u # add (or update) all tracked file -git commit -m "first commit" - -``` - +There is a chance that the `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the `.cruft.json` file. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again. E.g. with `git add -u # add (or update) all tracked file` and `git commit -m "first commit"` ``` Now that all the files of the newly created project have been committed, go ahead with the remaining steps: From 028fccb242e53574963a6a4ffa9fe5cacd74b233 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 12:04:21 +0100 Subject: [PATCH 03/20] update codecov docs and codecov action --- .../.github/workflows/test.yaml | 5 +- .../docs/developer_docs.md | 71 +++++++++++++------ 2 files changed, 52 insertions(+), 24 deletions(-) diff --git a/{{cookiecutter.project_name}}/.github/workflows/test.yaml b/{{cookiecutter.project_name}}/.github/workflows/test.yaml index 2f0ffd7a..75434b7a 100644 --- a/{{cookiecutter.project_name}}/.github/workflows/test.yaml +++ b/{{cookiecutter.project_name}}/.github/workflows/test.yaml @@ -56,7 +56,4 @@ jobs: run: | pytest -v --cov --color=yes - name: Upload coverage - env: - CODECOV_NAME: ${{ matrix.python }}-${{ matrix.os }} - run: | - codecov --required --flags=unittests + uses: codecov/codecov-action@v3 diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index ed357380..99211ca6 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -19,7 +19,7 @@ cruft create https://github.com/scverse/cookiecutter-scverse and you should have ``` -cd your-awesome-project +cd {{cookiecutter.project_name}} ``` into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github. @@ -27,10 +27,10 @@ You can follow the instructions directly on [github](https://docs.github.com/en/ Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. -Now that your new project repository has been created on github at `https://github.com/your-account/your-awesome-project` you can push your first commit to github. +Now that your new project repository has been created on github at `https://github.com/your-user-name/{{cookiecutter.project_name}}` you can push your first commit to github. To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: -Assuming you are in `/your/path/to/your-awesome-project`. Add all files and commit. +Assuming you are in `/your/path/to/{{cookiecutter.project_name}}`. Add all files and commit. ```bash # stage all files of your new repo @@ -56,19 +56,7 @@ git branch -M main git push -u origin main ``` -### Documentation on _readthedocs_ - -We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. -To enable readthedocs, head over to [their webiste][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 default name of the default branch has - recently changed from `master` to `main`. -- We recommend to enable 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](https://docs.readthedocs.io/en/stable/pull-requests.html). -- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. +Your project should be now available at `https://github.com/your-user-name/{{cookiecutter.project_name}}`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. ### Coverage tests with _Codecov_ @@ -77,13 +65,54 @@ Coverage tells what fraction of the code is "covered" by unit tests, thereby enc To enable coverage checks, head over to [codecov][] and sign in with your GitHub account. You'll find more information in "getting started" section of the [codecov docs][]. +In the `Actions` tab of your projects' github repository, you can see that the workflows are failing due to the **Upload coverage** step. The error message in the workflow should display something like: + +``` +... + Retrying 5/5 in 2s.. + {'detail': ErrorDetail(string='Could not find a repository, try using repo upload token', code='not_found')} +Error: 404 Client Error: Not Found for url: +... +``` + +While [codecov docs][] has a very extensive documentation on how to get started, _if_ you are using the default settings of this template we can assume that you are using [codecov][] in a github action workflow and hence you can make use of the [codecov bot][]. + +To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. +Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. + +The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-user-name/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the code coverage of this repository should be ~60%. + +If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: 1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard. -2. Go to the _Settings_ of your newly created repository on GitHub. -3. Go to _Security > Secrets > Actions_. -4. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov -5. Go back to Github Actions page an re-run previously failed jobs. + 1. If you have already set up the the repository by following the previous steps, you can directly go to the codecov repo webpage. +2. _Settings_ and copy **only** the token `_______-____-...`. +3. Go to the _Settings_ of your newly created repository on GitHub. +4. Go to _Security > Secrets > Actions_. +5. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov. +6. Past this additional lines in `/.github/workflows.test.yaml` under **Upload coverage** step + ```bash + - name: Upload coverage + uses: codecov/codecov-action@v3 + with: + token: ${{ secrets.CODECOV_TOKEN }} + ``` +7. Go back to Github Actions page an re-run previously failed jobs. + +### Documentation on _readthedocs_ + +We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. +To enable readthedocs, head over to [their webiste][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 to enable 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](https://docs.readthedocs.io/en/stable/pull-requests.html). +- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. ### Pre-commit checks @@ -403,6 +432,8 @@ open _build/html/index.html [scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html [codecov]: https://about.codecov.io/sign-up/ [codecov docs]: https://docs.codecov.com/docs +[codecov bot]: https://docs.codecov.com/docs/team-bot +[codecov app]: https://github.com/apps/codecov [pre-commit.ci]: https://pre-commit.ci/ [readthedocs.org]: https://readthedocs.org/ [myst-nb]: https://myst-nb.readthedocs.io/en/latest/ From 43d53d0b845fa6cfa469b80265a9d662849430a0 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 12:57:01 +0100 Subject: [PATCH 04/20] try escape cookiecutter --- {{cookiecutter.project_name}}/docs/developer_docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 99211ca6..34eb0d07 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -96,7 +96,7 @@ In brief, you need to: - name: Upload coverage uses: codecov/codecov-action@v3 with: - token: ${{ secrets.CODECOV_TOKEN }} + token: $"{{" secrets.CODECOV_TOKEN "}}" ``` 7. Go back to Github Actions page an re-run previously failed jobs. From 9993af20ed0539ef5524f393f25c02e75ea48111 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 13:01:16 +0100 Subject: [PATCH 05/20] try escape cookicutter again --- {{cookiecutter.project_name}}/docs/developer_docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 34eb0d07..1acb3924 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -96,7 +96,7 @@ In brief, you need to: - name: Upload coverage uses: codecov/codecov-action@v3 with: - token: $"{{" secrets.CODECOV_TOKEN "}}" + token: {{${{ secrets.CODECOV_TOKEN }}}} ``` 7. Go back to Github Actions page an re-run previously failed jobs. From 041ab87da9e9c077280a9eeff0959df54b274020 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 13:02:29 +0100 Subject: [PATCH 06/20] one more time --- {{cookiecutter.project_name}}/docs/developer_docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 1acb3924..c226b28d 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -96,7 +96,7 @@ In brief, you need to: - name: Upload coverage uses: codecov/codecov-action@v3 with: - token: {{${{ secrets.CODECOV_TOKEN }}}} + token: ${{ "{{" }}secrets.CODECOV_TOKEN{{ "}}" }} ``` 7. Go back to Github Actions page an re-run previously failed jobs. From b2a7d488d20c29e96db0d2567aae2bb3d94da256 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 13:10:45 +0100 Subject: [PATCH 07/20] add correct project ref --- .../docs/developer_docs.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index c226b28d..a82147c9 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -27,7 +27,11 @@ You can follow the instructions directly on [github](https://docs.github.com/en/ Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. -Now that your new project repository has been created on github at `https://github.com/your-user-name/{{cookiecutter.project_name}}` you can push your first commit to github. +```{note} +If you are looking at this document in the `cookiecutter-scverse-instance` repository documentation, throughout this document the name of this project should be the same. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. +``` + +Now that your new project repository has been created on github at `https://github.com/your-username/{{cookiecutter.project_name}}` you can push your first commit to github. To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: Assuming you are in `/your/path/to/{{cookiecutter.project_name}}`. Add all files and commit. @@ -49,14 +53,14 @@ Now that all the files of the newly created project have been committed, go ahea ```bash # update the `origin` of your local repo with the remote github link -git remote add origin https://github.com/giovp/temp_repo.git +git remote add origin https://github.com/your-username/{{cookiecutter.project_name}}.git # rename the default branch to main git branch -M main # push all your files to remote git push -u origin main ``` -Your project should be now available at `https://github.com/your-user-name/{{cookiecutter.project_name}}`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. +Your project should be now available at `https://github.com/your-username/{{cookiecutter.project_name}}`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. ### Coverage tests with _Codecov_ @@ -80,7 +84,7 @@ While [codecov docs][] has a very extensive documentation on how to get started, To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. -The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-user-name/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the code coverage of this repository should be ~60%. +The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-username/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the code coverage of this repository should be ~60%. If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: @@ -96,7 +100,7 @@ In brief, you need to: - name: Upload coverage uses: codecov/codecov-action@v3 with: - token: ${{ "{{" }}secrets.CODECOV_TOKEN{{ "}}" }} + token: ${{ "{{" }} secrets.CODECOV_TOKEN {{ "}}" }} ``` 7. Go back to Github Actions page an re-run previously failed jobs. From a140d2578753c99c0b52f9554760917795ca78dc Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 13:21:18 +0100 Subject: [PATCH 08/20] improve note --- {{cookiecutter.project_name}}/docs/developer_docs.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index a82147c9..09ae8666 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -23,13 +23,13 @@ cd {{cookiecutter.project_name}} ``` into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github. -You can follow the instructions directly on [github](https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui). +You can follow the instructions directly on [github quickstart guide][]. Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. -```{note} -If you are looking at this document in the `cookiecutter-scverse-instance` repository documentation, throughout this document the name of this project should be the same. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. -``` +:::{note} +If you are looking at this document in the `[cookiecutter-scverse-instance][]` repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. +::: Now that your new project repository has been created on github at `https://github.com/your-username/{{cookiecutter.project_name}}` you can push your first commit to github. To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: @@ -434,6 +434,8 @@ open _build/html/index.html [scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html +[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui [codecov]: https://about.codecov.io/sign-up/ [codecov docs]: https://docs.codecov.com/docs [codecov bot]: https://docs.codecov.com/docs/team-bot From 32cd8b1be259730f7f07e3c933853842d3082bcf Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 13:40:46 +0100 Subject: [PATCH 09/20] fixes and split developer and contributing --- .../docs/contributing.md | 169 ++++++++++++++++++ .../docs/developer_docs.md | 37 ++-- {{cookiecutter.project_name}}/docs/index.md | 1 + 3 files changed, 192 insertions(+), 15 deletions(-) create mode 100644 {{cookiecutter.project_name}}/docs/contributing.md diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md new file mode 100644 index 00000000..c53f5113 --- /dev/null +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -0,0 +1,169 @@ +# Contributing guide + +Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. +This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important +information to get you started on contributing. + +We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer +to the [scanpy developer guide][]. + +## Installing dev dependencies + +In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build +the documentation_. It's easy to install them using `pip`: + +```bash +cd {{ cookiecutter.project_name }} +pip install -e ".[dev,test,doc]" +``` + +## Code-style + +This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either +automatically fix issues with the code, or raise an error message. See [pre-commit checks](developer_docs.md#pre-commit-checks) for +a full list of checks enabled for this repository. + +To enable pre-commit locally, simply run + +```bash +pre-commit install +``` + +in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. + +Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before +pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. + +If pre-commit.ci added a commit on a branch you still have been working on locally, simply use + +```bash +git pull --rebase +``` + +to integrate the changes into yours. + +Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] +and [prettier][prettier-editors]. + +[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html +[prettier-editors]: https://prettier.io/docs/en/editors.html + +## Writing tests + +This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added +to the package. + +Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the +command line by executing + +```bash +pytest +``` + +in the root of the repository. Continuous integration will automatically run the tests on all pull requests. + +[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests + +## Making a release + +### Updating the version number + +Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes, +> 2. MINOR version when you add functionality in a backwards compatible manner, and +> 3. PATCH version when you make backwards compatible bug fixes. +> +> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. + +We use [bump2version][] to automatically update the version number in all places and automatically create a git tag. +Run one of the following commands in the root of the repository + +```bash +bump2version patch +bump2version minor +bump2version major +``` + +Once you are done, run + +``` +git push --tags +``` + +to publish the created tag on GitHub. + +[bump2version]: https://github.com/c4urself/bump2version + +### Upload on PyPI + +Please follow the [Python packaging tutorial][]. + +It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] +in the cookiecutter-scverse template. + +[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives +[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88 + +## Writing documentation + +Please write documentation for your package. 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 + +See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information +on how to write documentation. + +### Tutorials with myst-nb and jupyter notebooks + +The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. +Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. +It is your reponsibility to update and re-run the notebook whenever necessary. + +If you are interested in automatically running notebooks as part of the continuous integration, please check +out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse` +repository. + +#### 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` + +#### Building the docs locally + +```bash +cd docs +make html +open _build/html/index.html +``` + + + +[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html +[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui +[codecov]: https://about.codecov.io/sign-up/ +[codecov docs]: https://docs.codecov.com/docs +[codecov bot]: https://docs.codecov.com/docs/team-bot +[codecov app]: https://github.com/apps/codecov +[pre-commit.ci]: https://pre-commit.ci/ +[readthedocs.org]: https://readthedocs.org/ +[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ +[jupytext]: https://jupytext.readthedocs.io/en/latest/ +[pre-commit]: https://pre-commit.com/ +[anndata]: https://github.com/scverse/anndata +[mudata]: https://github.com/scverse/mudata +[pytest]: https://docs.pytest.org/ +[semver]: https://semver.org/ +[sphinx]: https://www.sphinx-doc.org/en/master/ +[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html +[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html +[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html +[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 09ae8666..656923ab 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -28,7 +28,7 @@ Since `cruft` already populated the local repository of your project with all th If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. :::{note} -If you are looking at this document in the `[cookiecutter-scverse-instance][]` repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. +If you are looking at this document in the [cookiecutter-scverse-instance][] repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. ::: Now that your new project repository has been created on github at `https://github.com/your-username/{{cookiecutter.project_name}}` you can push your first commit to github. @@ -43,12 +43,18 @@ git add --all git commit -m "first commit" ``` -You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](developer_docs.md#pre-commit-checks) in this document. +You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](#pre-commit-checks) in this document. -```{note} -There is a chance that the `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the `.cruft.json` file. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again. E.g. with `git add -u # add (or update) all tracked file` and `git commit -m "first commit"` +:::{note} +There is a chance that `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the file `.cruft.json`. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again: + +```bash + git add -u # update all tracked file + git commit -m "first commit" ``` +::: + Now that all the files of the newly created project have been committed, go ahead with the remaining steps: ```bash @@ -84,30 +90,29 @@ While [codecov docs][] has a very extensive documentation on how to get started, To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. -The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-username/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the code coverage of this repository should be ~60%. +The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-username/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the coverage of this repository should be ~60%. -If your repository is private, you will have to specify an additional token in the repository secrets. -In brief, you need to: +If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: 1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard. - 1. If you have already set up the the repository by following the previous steps, you can directly go to the codecov repo webpage. -2. _Settings_ and copy **only** the token `_______-____-...`. -3. Go to the _Settings_ of your newly created repository on GitHub. + - If you have already set up codecov in the repository by following the previous steps, you can directly go to the codecov repo webpage. +2. Go to _Settings_ and copy **only** the token `_______-____-...`. +3. Go to _Settings_ of your newly created repository on GitHub. 4. Go to _Security > Secrets > Actions_. 5. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov. -6. Past this additional lines in `/.github/workflows.test.yaml` under **Upload coverage** step +6. Past these additional lines in `/.github/workflows.test.yaml` under the **Upload coverage** step: ```bash - name: Upload coverage uses: codecov/codecov-action@v3 with: - token: ${{ "{{" }} secrets.CODECOV_TOKEN {{ "}}" }} + token: {% raw %}${{ secrets.CODECOV_TOKEN }}{% endraw %} ``` -7. Go back to Github Actions page an re-run previously failed jobs. +7. Go back to github `Actions` page an re-run previously failed jobs. ### Documentation on _readthedocs_ We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. -To enable readthedocs, head over to [their webiste][readthedocs.org] and sign in with your GitHub account. +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 @@ -118,6 +123,8 @@ On the RTD dashboard choose "Import a Project" and follow the instructions to ad the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html). - 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). + ### Pre-commit checks [Pre-commit][] checks are fast programs that @@ -186,7 +193,7 @@ The following pre-commit checks are for errors and inconsistencies: ### API design -Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] datastructures and typically use an API +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 diff --git a/{{cookiecutter.project_name}}/docs/index.md b/{{cookiecutter.project_name}}/docs/index.md index 23a1e198..9eb9b24c 100644 --- a/{{cookiecutter.project_name}}/docs/index.md +++ b/{{cookiecutter.project_name}}/docs/index.md @@ -9,6 +9,7 @@ api.md changelog.md developer_docs.md +contributing.md references.md notebooks/example From 2ffe3b1c3f99eee0e8be6f8ea05001a53e2946cb Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 14:08:19 +0100 Subject: [PATCH 10/20] add moving forward --- .../docs/developer_docs.md | 175 +----------------- 1 file changed, 4 insertions(+), 171 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 656923ab..f062d551 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -123,7 +123,7 @@ On the RTD dashboard choose "Import a Project" and follow the instructions to ad the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html). - 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). +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). ### Pre-commit checks @@ -266,177 +266,10 @@ Don't forget to update the [Making a release section](#making-a-release) in this [hatch-vcs]: https://pypi.org/project/hatch-vcs/ -## Contributing guide +## Moving forward -Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. -This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important -information to get you started on contributing. - -We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer -to the [scanpy developer guide][]. - -### Installing dev dependencies - -In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build -the documentation_. It's easy to install them using `pip`: - -```bash -cd {{ cookiecutter.project_name }} -pip install -e ".[dev,test,doc]" -``` - -### Code-style - -This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either -automatically fix issues with the code, or raise an error message. See [pre-commit checks](#pre-commit-checks) for -a full list of checks enabled for this repository. - -To enable pre-commit locally, simply run - -```bash -pre-commit install -``` - -in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. - -Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before -pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. - -If pre-commit.ci added a commit on a branch you still have been working on locally, simply use - -```bash -git pull --rebase -``` - -to integrate the changes into yours. - -Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] -and [prettier][prettier-editors]. - -[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html -[prettier-editors]: https://prettier.io/docs/en/editors.html - -### Writing tests - -This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added -to the package. - -Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the -command line by executing - -```bash -pytest -``` - -in the root of the repository. Continuous integration will automatically run the tests on all pull requests. - -[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests - -### Automated template sync - -Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check -if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request -proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest -coding standards. - -It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the -diff is created. You need to manually address these changes and remove the `.rej` file when you are done. -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`. - -::: - -[cruft]: https://cruft.github.io/cruft/ -[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project - -### Making a release - -#### Updating the version number - -Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief - -> Given a version number MAJOR.MINOR.PATCH, increment the: -> -> 1. MAJOR version when you make incompatible API changes, -> 2. MINOR version when you add functionality in a backwards compatible manner, and -> 3. PATCH version when you make backwards compatible bug fixes. -> -> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. - -We use [bump2version][] to automatically update the version number in all places and automatically create a git tag. -Run one of the following commands in the root of the repository - -```bash -bump2version patch -bump2version minor -bump2version major -``` - -Once you are done, run - -``` -git push --tags -``` - -to publish the created tag on GitHub. - -[bump2version]: https://github.com/c4urself/bump2version - -#### Upload on PyPI - -Please follow the [Python packaging tutorial][]. - -It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] -in the cookiecutter-scverse template. - -[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives -[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88 - -### Writing documentation - -Please write documentation for your package. 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 - -See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information -on how to write documentation. - -### Tutorials with myst-nb and jupyter notebooks - -The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. -Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. -It is your reponsibility to update and re-run the notebook whenever necessary. - -If you are interested in automatically running notebooks as part of the continuous integration, please check -out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse` -repository. - -#### 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` - -#### Building the docs locally - -```bash -cd docs -make html -open _build/html/index.html -``` +You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start. +For everything else related to documentation, code style, testing and publishing, please refer to the [contributing documentation][contributing.md# contributing guide]. From 65dbd5bfce16f951b0df3fd3950c4c0751d43336 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 14:13:55 +0100 Subject: [PATCH 11/20] fix link --- {{cookiecutter.project_name}}/docs/developer_docs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index f062d551..7052ab22 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -262,14 +262,14 @@ In `pyproject.toml` add the following changes, and you are good to go! omit = [ ``` -Don't forget to update the [Making a release section](#making-a-release) in this document accordingly, after you are done! +Don't forget to update the [Making a release section](contributing.md#making-a-release) in this document accordingly, after you are done! [hatch-vcs]: https://pypi.org/project/hatch-vcs/ ## Moving forward You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start. -For everything else related to documentation, code style, testing and publishing, please refer to the [contributing documentation][contributing.md# contributing guide]. +For everything else related to documentation, code style, testing and publishing your project ot pypi, please refer to the [contributing docs](contributing.md#contributing-guide). From 2690cb40f4657c2e6c7653342c9df02c59169938 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 14:34:06 +0100 Subject: [PATCH 12/20] fixes --- .../docs/developer_docs.md | 66 +++++++++++++------ 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 7052ab22..dc2acbde 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -4,7 +4,7 @@ Welcome to the developer guidelines! This document is split into two parts: 1. The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect continuous integration services and documents initial set-up of the repository. -2. The [contributor guide](#contributing-guide). It contains information relevant to all developers who want to make a contribution. +2. The [contributor guide](contributing.md#contributing-guide). It contains information relevant to all developers who want to make a contribution. ## Setting up the repository @@ -71,7 +71,7 @@ Your project should be now available at `https://github.com/your-username/{{cook ### Coverage tests with _Codecov_ Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to -[write tests](#writing-tests). +[write tests](contributing.md#writing-tests). To enable coverage checks, head over to [codecov][] and sign in with your GitHub account. You'll find more information in "getting started" section of the [codecov docs][]. @@ -184,29 +184,14 @@ The following pre-commit checks are for errors and inconsistencies: - **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. -#### Notes on pre-commit checks +### How to disable or add pre-commit checks - To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#ignore-certain-lint-warnings). - You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file. Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**. -### API design - -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 - -You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, -there may also be good reasons to choose a different approach, e.g. using an object-oriented API. - -[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html - -### Ignore certain lint warnings +### How to ignore certain lint warnings The [pre-commit checks](#pre-commit-checks) include [flake8](https://flake8.pycqa.org/en/latest/) which checks for errors in Python files, including stylistic errors. @@ -230,10 +215,25 @@ W504 [flake8 guide]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html +### API design + +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 + +You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, +there may also be good reasons to choose a different approach, e.g. using an object-oriented API. + +[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html + ### Using VCS-based versioning By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with -bump2version](#making-a-release). If you prefer to have your project automatically infer version numbers from git +bump2version](contributing.md#making-a-release). If you prefer to have your project automatically infer version numbers from git tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][]. In `pyproject.toml` add the following changes, and you are good to go! @@ -266,6 +266,32 @@ Don't forget to update the [Making a release section](contributing.md#making-a-r [hatch-vcs]: https://pypi.org/project/hatch-vcs/ +### Automated template sync + +Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check +if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request +proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest +coding standards. + +It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the +diff is created. You need to manually address these changes and remove the `.rej` file when you are done. +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`. + +::: + +[cruft]: https://cruft.github.io/cruft/ +[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project + ## Moving forward You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start. From ff1952f15749a7b752edaf2c9bff4411d171647e Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 14:38:01 +0100 Subject: [PATCH 13/20] update --- {{cookiecutter.project_name}}/docs/developer_docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index dc2acbde..96284580 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -186,7 +186,7 @@ The following pre-commit checks are for errors and inconsistencies: ### How to disable or add pre-commit checks -- To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#ignore-certain-lint-warnings). +- To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#how-to-ignore-certain-lint-warnings). - You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file. Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**. From 8b0151d50aed48835c0ba3701db96f0d7ac8e070 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 14:44:23 +0100 Subject: [PATCH 14/20] update title --- {{cookiecutter.project_name}}/docs/developer_docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 96284580..cdc11f0b 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -1,4 +1,4 @@ -# Developer documentation +# Using this template Welcome to the developer guidelines! This document is split into two parts: From 5fe6636417e9199db1edc76b5e0feddeb54dcf04 Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 15:15:35 +0100 Subject: [PATCH 15/20] add publishing --- .../docs/contributing.md | 29 +++++++++++++++++-- {{cookiecutter.project_name}}/pyproject.toml | 3 +- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index c53f5113..4cabbb70 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -64,7 +64,7 @@ in the root of the repository. Continuous integration will automatically run the [scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests -## Making a release +## Publishing a release ### Updating the version number @@ -97,9 +97,31 @@ to publish the created tag on GitHub. [bump2version]: https://github.com/c4urself/bump2version -### Upload on PyPI +### Building and publishing the package on PyPI -Please follow the [Python packaging tutorial][]. +Python packages are not distributed as source code, but as _distributions_. The most common distribution format is the so-called _wheel_. To build a _wheel_, run + +```bash +python -m build +``` + +This command creates a _source archive_ and a _wheel_, which are required for publishing your package to [PyPI][]. These files are created directly in the root of the repository. + +Before uploading them to [PyPI][] you can check that your _distribution_ is valid by running: + +```bash +twine check dist/* +``` + +and finally publishing it with: + +```bash +twine upload dist/* +``` + +Provide your username and password when requested and then go check out your package on [PyPI][]! + +For more information, follow the [Python packaging tutorial][]. It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] in the cookiecutter-scverse template. @@ -167,3 +189,4 @@ open _build/html/index.html [numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html [numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html [sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints +[pypi]: https://pypi.org/ diff --git a/{{cookiecutter.project_name}}/pyproject.toml b/{{cookiecutter.project_name}}/pyproject.toml index 90d91c8f..38fff8d6 100644 --- a/{{cookiecutter.project_name}}/pyproject.toml +++ b/{{cookiecutter.project_name}}/pyproject.toml @@ -29,7 +29,8 @@ dependencies = [ dev = [ # CLI for bumping the version number "bump2version", - "pre-commit" + "pre-commit", + "twine>=4.0.2" ] doc = [ "sphinx>=4", From 5bc4f355cf7e15589cf79b60fd9bfe5a0f9c327e Mon Sep 17 00:00:00 2001 From: giovp Date: Fri, 9 Dec 2022 15:24:07 +0100 Subject: [PATCH 16/20] fixes --- {{cookiecutter.project_name}}/docs/contributing.md | 4 ++++ {{cookiecutter.project_name}}/docs/developer_docs.md | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index 4cabbb70..3a2e0ed9 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -50,6 +50,10 @@ and [prettier][prettier-editors]. ## Writing tests +```{note} +Remember to first install the package with `pip install '-e[dev,test]'` +``` + This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added to the package. diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index cdc11f0b..5f095009 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -233,7 +233,7 @@ there may also be good reasons to choose a different approach, e.g. using an obj ### Using VCS-based versioning By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with -bump2version](contributing.md#making-a-release). If you prefer to have your project automatically infer version numbers from git +bump2version](contributing.md#publishing-a-release). If you prefer to have your project automatically infer version numbers from git tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][]. In `pyproject.toml` add the following changes, and you are good to go! @@ -262,7 +262,7 @@ In `pyproject.toml` add the following changes, and you are good to go! omit = [ ``` -Don't forget to update the [Making a release section](contributing.md#making-a-release) in this document accordingly, after you are done! +Don't forget to update the [Making a release section](contributing.md#publishing-a-release) in this document accordingly, after you are done! [hatch-vcs]: https://pypi.org/project/hatch-vcs/ From 6d97bb11bb3975057e4084b64e5ea0f9b3ab1359 Mon Sep 17 00:00:00 2001 From: Giovanni Palla <25887487+giovp@users.noreply.github.com> Date: Sat, 17 Dec 2022 09:54:28 +0100 Subject: [PATCH 17/20] Update {{cookiecutter.project_name}}/docs/contributing.md Co-authored-by: Isaac Virshup --- {{cookiecutter.project_name}}/docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index 3a2e0ed9..528f9f67 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -135,7 +135,7 @@ in the cookiecutter-scverse template. ## Writing documentation -Please write documentation for your package. This project uses [sphinx][] with the following features: +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). From a6843caa969c58f518909c6172107143a8d998be Mon Sep 17 00:00:00 2001 From: giovp Date: Sat, 17 Dec 2022 10:03:24 +0100 Subject: [PATCH 18/20] add project name --- {{cookiecutter.project_name}}/docs/developer_docs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/developer_docs.md index 5f095009..0d0fd124 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/developer_docs.md @@ -31,7 +31,7 @@ If you are familiar with git and knows how to handle git conflicts, you can go a If you are looking at this document in the [cookiecutter-scverse-instance][] repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `{{cookiecutter.project_name}}`. ::: -Now that your new project repository has been created on github at `https://github.com/your-username/{{cookiecutter.project_name}}` you can push your first commit to github. +Now that your new project repository has been created on github at `https://github.com/{{cookiecutter.github_user}}/{{cookiecutter.project_name}}` you can push your first commit to github. To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: Assuming you are in `/your/path/to/{{cookiecutter.project_name}}`. Add all files and commit. @@ -59,14 +59,14 @@ Now that all the files of the newly created project have been committed, go ahea ```bash # update the `origin` of your local repo with the remote github link -git remote add origin https://github.com/your-username/{{cookiecutter.project_name}}.git +git remote add origin https://github.com/{{cookiecutter.github_user}}/{{cookiecutter.project_name}}.git # rename the default branch to main git branch -M main # push all your files to remote git push -u origin main ``` -Your project should be now available at `https://github.com/your-username/{{cookiecutter.project_name}}`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. +Your project should be now available at `https://github.com/{{cookiecutter.github_user}}/{{cookiecutter.project_name}}`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. ### Coverage tests with _Codecov_ @@ -90,7 +90,7 @@ While [codecov docs][] has a very extensive documentation on how to get started, To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. -The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/your-username/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the coverage of this repository should be ~60%. +The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/{{cookiecutter.github_user}}/{{cookiecutter.project_name}}`. You might have to wait couple of minutes and the coverage of this repository should be ~60%. If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: From eb1e7d45db4b35913d00bfe831e9062e1ebc9343 Mon Sep 17 00:00:00 2001 From: giovp Date: Sat, 17 Dec 2022 10:06:57 +0100 Subject: [PATCH 19/20] rename template --- README.md | 14 +++++++------- .../.github/workflows/sync.yaml | 2 +- {{cookiecutter.project_name}}/docs/contributing.md | 4 ++-- {{cookiecutter.project_name}}/docs/index.md | 2 +- .../docs/{developer_docs.md => template_usage.md} | 2 +- 5 files changed, 12 insertions(+), 12 deletions(-) rename {{cookiecutter.project_name}}/docs/{developer_docs.md => template_usage.md} (99%) diff --git a/README.md b/README.md index de473bfc..e9e62bd0 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Don't forget to create a repository on GitHub and upload your project. Your repository is now ready. However, to use all features of the template you will need to set up the following online services. Clicking on the links will take you to the respective sections of the developer documentation. -The developer documentation is also shipped as part of the template in `docs/developer_docs.md`. +The developer documentation is also shipped as part of the template in `docs/template_usage.md`. 1. [pre-commit.ci][setup-pre-commit] to check for inconsistencies and to enforce a code style 2. [readthedocs.org][setup-rtd] to build and host documentation @@ -66,7 +66,7 @@ All CI checks should pass, you are ready to start developing your new tool! ### Customizations -Further instructions on using this template can be found in the [dev docs included in the project](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html). +Further instructions on using this template can be found in the [dev docs included in the project](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html). ### Committment @@ -90,11 +90,11 @@ Note that when creating a new release, changes will be propagated to packages us -[setup-pre-commit]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#pre-commit-checks -[setup-rtd]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#documentation-on-readthedocs -[setup-codecov]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#coverage-tests-with-codecov -[write-tests]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#writing-tests -[write-docs]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#writing-documentation +[setup-pre-commit]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#pre-commit-checks +[setup-rtd]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#documentation-on-readthedocs +[setup-codecov]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#coverage-tests-with-codecov +[write-tests]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#writing-tests +[write-docs]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#writing-documentation [readthedocs]: https://readthedocs.org/ [myst-nb]: https://myst-nb.readthedocs.io/ [pre-commit]: https://pre-commit.com/ diff --git a/{{cookiecutter.project_name}}/.github/workflows/sync.yaml b/{{cookiecutter.project_name}}/.github/workflows/sync.yaml index 52194992..da9b5206 100644 --- a/{{cookiecutter.project_name}}/.github/workflows/sync.yaml +++ b/{{cookiecutter.project_name}}/.github/workflows/sync.yaml @@ -43,4 +43,4 @@ jobs: manually merge these changes.** For more information about the template sync, please refer to the - [template documentation](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html#automated-template-sync). + [template documentation](https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html#automated-template-sync). diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index 528f9f67..cb0f894f 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -20,7 +20,7 @@ pip install -e ".[dev,test,doc]" ## Code-style This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either -automatically fix issues with the code, or raise an error message. See [pre-commit checks](developer_docs.md#pre-commit-checks) for +automatically fix issues with the code, or raise an error message. See [pre-commit checks](template_usage.md#pre-commit-checks) for a full list of checks enabled for this repository. To enable pre-commit locally, simply run @@ -173,7 +173,7 @@ open _build/html/index.html [scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html -[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html [github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui [codecov]: https://about.codecov.io/sign-up/ [codecov docs]: https://docs.codecov.com/docs diff --git a/{{cookiecutter.project_name}}/docs/index.md b/{{cookiecutter.project_name}}/docs/index.md index 9eb9b24c..04d594a8 100644 --- a/{{cookiecutter.project_name}}/docs/index.md +++ b/{{cookiecutter.project_name}}/docs/index.md @@ -8,7 +8,7 @@ api.md changelog.md -developer_docs.md +template_usage.md contributing.md references.md diff --git a/{{cookiecutter.project_name}}/docs/developer_docs.md b/{{cookiecutter.project_name}}/docs/template_usage.md similarity index 99% rename from {{cookiecutter.project_name}}/docs/developer_docs.md rename to {{cookiecutter.project_name}}/docs/template_usage.md index 0d0fd124..8d6d550b 100644 --- a/{{cookiecutter.project_name}}/docs/developer_docs.md +++ b/{{cookiecutter.project_name}}/docs/template_usage.md @@ -300,7 +300,7 @@ For everything else related to documentation, code style, testing and publishing [scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html -[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/developer_docs.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html [github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui [codecov]: https://about.codecov.io/sign-up/ [codecov docs]: https://docs.codecov.com/docs From 3c491b7e3738d0efd33550c8fea2aee947d0c52f Mon Sep 17 00:00:00 2001 From: giovp Date: Sat, 17 Dec 2022 10:13:32 +0100 Subject: [PATCH 20/20] added note on local pre-commits --- {{cookiecutter.project_name}}/docs/contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/{{cookiecutter.project_name}}/docs/contributing.md b/{{cookiecutter.project_name}}/docs/contributing.md index cb0f894f..abe6e21d 100644 --- a/{{cookiecutter.project_name}}/docs/contributing.md +++ b/{{cookiecutter.project_name}}/docs/contributing.md @@ -41,6 +41,7 @@ git pull --rebase ``` to integrate the changes into yours. +While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] and [prettier][prettier-editors].