From 2ca8c0bcdc32f01d9e0d0d3f7f3d8eb180b6827a Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:36 +0200 Subject: [PATCH 1/6] docs: remove links to linting config files --- docs/develop.md | 39 ++------------------------------------- 1 file changed, 2 insertions(+), 37 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index b7928a14..da240c05 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -340,43 +340,8 @@ See more info at {ref}`develop:Jupyter Notebooks`. Linters point out when certain style conventions are not correctly followed. Unlike with {ref}`formatters `, you have to fix the errors -yourself. - -As mentioned in {ref}`develop:Automated coding conventions`, style conventions -are formulated in config files. For linters, we use the following: - - - -- [`.cspell.json`](https://github.com/ComPWA/ampform/blob/main/.cspell.json) - - [cSpell: spell checker for code](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell) -- [`.markdownlint.json`](https://github.com/ComPWA/ampform/blob/main/.markdownlint.json) - - [markdownlint](https://github.com/DavidAnson/markdownlint) -- [`pyproject.toml`](https://github.com/ComPWA/ampform/blob/main/pyproject.toml) - - {ref}`black ` - - {ref}`isort ` -- [`.mypy.ini`](https://github.com/ComPWA/ampform/blob/main/.mypy.ini) - - [mypy](http://mypy-lang.org) -- [`.prettierrc`](https://github.com/ComPWA/ampform/blob/main/.prettierrc) - - [Prettier](https://prettier.io) -- [`pyrightconfig.json`](https://github.com/ComPWA/ampform/blob/main/pyrightconfig.json) - - [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) - - [Pyright](https://github.com/microsoft/pyright) -- [`tox.ini`](https://github.com/ComPWA/ampform/blob/main/tox.ini) - - [flake8](https://flake8.pycqa.org) - - [pydocstyle](https://pydocstyle.pycqa.org) - - [pytest](https://docs.pytest.org) - -::::{toggle} - -:::{note} - -As an illustration of automated checks, we list the files here with links to -the actual files as to ensure that these files still exist and that this -documentation remains up to date. - -::: - -:::: +yourself. As mentioned in {ref}`develop:Automated coding conventions`, style +conventions are formulated in config files. ### Spelling From 2a3961b8aabeb2a9ebd07d1be59ec14727b30b94 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:37 +0200 Subject: [PATCH 2/6] fix: fix dropdown menu Conda and VSCode --- docs/develop.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index da240c05..6a8b4f0a 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -754,13 +754,6 @@ as the VSCode settings that come with this are folder settings. :::{dropdown} Conda and VSCode -:::{tip} - -We would gladly extend the environment configuration in such a way that other -editors behave in a standardized way as well. Let us know - -::: - ComPWA projects are best developed {ref}`with Conda ` and VSCode. The complete developer install procedure then becomes: @@ -773,6 +766,8 @@ conda activate pwa # or whatever the environment name is code . # open folder in VSCode ``` +::: + ## Writing durable software ComPWA strives to follow best practices from software development in industry. From ba71b7fe1bc658e061dcdd7052fec47952612b78 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:38 +0200 Subject: [PATCH 3/6] docs: recommend C++ Core Guidelines --- docs/develop.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/develop.md b/docs/develop.md index 6a8b4f0a..89a6db76 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -816,7 +816,7 @@ Do you have other recommendations? Edit this page - [The different types of software testing ― Atlassian](https://www.atlassian.com/continuous-delivery/software-testing/types-of-software-testing) - [Types of Software Testing: 100 Examples of Different Testing Types ― Guru99](https://www.guru99.com/types-of-software-testing.html) -```{rubric} Design patterns +```{rubric} Software Design ``` @@ -832,6 +832,9 @@ Do you have other recommendations? Edit this page ["Gang of Four" (GOF) book](https://en.wikipedia.org/wiki/Design_Patterns): _Design Patterns_ (1994) by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides {cite}`gammaDesignPatternsElements1995` +- [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines): + while this document provides intended for C++ developers, it is an excellent, + up-to-date set of guidelines that apply to any programming language. ```{rubric} Algorithms From 84bb05e42f1a61bfa60b1894ba279ab2aaaba394 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:38 +0200 Subject: [PATCH 4/6] docs: improve wording virtual environments --- docs/develop.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 89a6db76..3a1ae39b 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -61,23 +61,24 @@ framework or use the developer tools. [Conda/Anaconda](https://www.anaconda.com) can be installed without administrator rights, see instructions on -[this page](https://www.anaconda.com/distribution). In addition, Conda can -install more than just Python packages. +[this page](https://conda.io/projects/conda/en/latest/user-guide/install/index.html). +In addition, Conda can install more than just Python packages. All packages {ref}`maintained by the ComPWA organization ` provide a [Conda environment file](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) ([`environment.yml`](https://github.com/ComPWA/ampform/blob/main/environment.yml)) -that defines the minimal dependencies to run the framework. To create an -environment specific for this package, simply navigate to the main folder of -the source code and run: +that defines all requirements when working on the source code of that +repository. To create an environment specific for this repository, simply +navigate to the main folder of the source code and run: ```shell conda env create ``` Conda now creates an environment with a name that is defined in the -{file}`environment.yml` file. In addition, it will install the framework in +[`environment.yml`](https://github.com/ComPWA/ampform/blob/main/environment.yml) +file. In addition, it will install the framework itself in ["editable" mode](#editable-installation), so that you can start developing right away. @@ -85,9 +86,9 @@ right away. :::{tabbed} Python venv -Alternatively, you can use -[Python's `venv`](https://docs.python.org/3/library/venv.html), if you have -that available on your system. Navigate to some convenient folder and run: +If you have [Python's `venv`](https://docs.python.org/3/library/venv.html), +available on your system, you can create a virtual environment with it. +Navigate to some convenient folder and run: ```shell python3 -m venv ./venv @@ -100,8 +101,9 @@ contained. To activate the environment, run: source ./venv/bin/activate ``` -Now you can safely install the package you want to working on, as well as any -dependencies (see ["editable" mode](#editable-installation)): +Now you can safely install the package you want to work on (see +["editable" mode](#editable-installation)), as well as any additional required +packages (see [optional dependencies](#optional-dependencies)): ```shell pip install -e . From 0de77809d7ba0763ce2772cb49a6ff0ddbc637f5 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:39 +0200 Subject: [PATCH 5/6] docs: improve wording pinned requirements --- docs/develop.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index 3a1ae39b..ffb5c3eb 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -168,8 +168,8 @@ These files can be used to 'pin' all versions of installed packages as follows: :::{margin} -Requirements may differ per Python version. Each version of Python therefore -requires a different constraint file. +Requirements may differ per Python version, so there is one constraint file for +each version of Python that the package supports. ::: @@ -185,20 +185,20 @@ python3 -m pip install -c .constraints/py-3.8.txt -e .[test] python3 -m pip install -c .constraints/py-3.8.txt -e .[dev] ``` -:::{margin} - -Constraint files are updated automatically with +The constraint files are updated automatically with [`pip-tools`](https://github.com/jazzband/pip-tools) through -{ref}`develop:GitHub Actions`. - -::: +{ref}`develop:GitHub Actions`. See +[`requirements-pr.yml`](https://github.com/ComPWA/ampform/actions/workflows/requirements-pr.yml) +and +[`requirements-cron.yml`](https://github.com/ComPWA/ampform/actions/workflows/requirements-cron.yml). :::{note} -This set-up ensures that the framework _deterministic and reproducible_ (up to -testing) for all commits, which is vital for both users (doing analysis) and -for developers ({ref}`continuous integration `). In -other words, it provides a way out of +Constraint files ensure that the framework is _deterministic and reproducible_ +(up to testing) _for all commits and versions_, which is vital for both users +(doing analysis) and for developers (for instance with +{ref}`continuous integration `). In other words, it +provides a way out of ["dependency hell"](https://en.wikipedia.org/wiki/Dependency_hell). ::: @@ -216,7 +216,7 @@ pip install -c .constraints/py3.8.txt -e .[dev] ``` If you still have problems, it may be that certain dependencies have become -redundant or conflicting. In that case, trash the virtual environment and +redundant. In that case, trash the virtual environment and {ref}`create a new one `. ## Automated coding conventions From fe42747c83f9c46bcc2a83020a923187b1c62f67 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 15 Oct 2021 21:29:40 +0200 Subject: [PATCH 6/6] docs: fix remaining issues after re-read --- docs/develop.md | 90 ++++++++++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/docs/develop.md b/docs/develop.md index ffb5c3eb..6b050c84 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -7,10 +7,10 @@ This page describes some of the tools and conventions followed by [Common Partial Wave Analysis](https://github.com/ComPWA). Where possible, we use the [source code of the AmpForm repository](https://github.com/ComPWA/AmpForm) as -example, because its file structure is comparable to that of ComPWA +example, because its file structure is comparable to that of other ComPWA repositories. -::::{tip} To start developing, simply run the following in the a cloned +::::{tip} To start developing, simply run the following from a cloned repository on your machine: :::{tabbed} Conda @@ -244,8 +244,9 @@ can be formulated through those config files. ### Pre-commit All {ref}`style checks ` are enforced through a tool -called [{command}`pre-commit`](https://pre-commit.com). This tool needs to be -activated, but only once, after you clone the repository: +called [{command}`pre-commit`](https://pre-commit.com). It's best to activate +this tool locally as well. This has to be done only once, after you clone the +repository: ```shell pre-commit install @@ -258,8 +259,8 @@ checks, it may take some time to initialize. ::: -Upon committing, {command}`pre-commit` now runs a set of checks as defined in -the file +Upon committing, {command}`pre-commit` runs a set of checks as defined in the +file [{file}`.pre-commit-config.yaml`](https://github.com/ComPWA/ampform/blob/main/.pre-commit-config.yaml) over all staged files. You can also quickly run all checks over _all_ indexed files in the repository with the command: @@ -268,10 +269,12 @@ files in the repository with the command: pre-commit run -a ``` -This command is also run on GitHub actions whenever you -{ref}`submit a pull request `, ensuring that all files -in the repository follow the same conventions as set in the config files of -these tools. +Whenever you {ref}`submit a pull request `, this command +is automatically run +[on GitHub actions](https://github.com/ComPWA/ampform/actions/workflows/ci-style.yml) +and [on pre-commit.ci](https://results.pre-commit.ci/install/github/18435973) , +ensuring that all files in the repository follow the same conventions as set in +the config files of these tools. ### Tox @@ -296,7 +299,7 @@ to **run tox before submitting a pull request!** -More specialized {command}`tox` tests are defined in the +More specialized {command}`tox` job are defined in the [`tox.ini`](https://github.com/ComPWA/ampform/blob/main/tox.ini) config file, under each {code}`testenv` section. You can list all environments, along with a description of what they do, by running: @@ -305,18 +308,16 @@ description of what they do, by running: tox -av ``` -Note that {command}`tox` works with its own virtual environments. These -environments install -{ref}`'pinned' dependencies `. - ### GitHub Actions All {ref}`style checks `, testing of the {ref}`documentation and links `, and {ref}`unit tests ` are performed upon each pull request through [GitHub Actions](https://docs.github.com/en/actions) (see status -overview [here](https://github.com/ComPWA/ampform/actions)). All checks -performed for each PR have to pass before the PR can be merged. +overview [here](https://github.com/ComPWA/ampform/actions)). The checks are +defined under the +[`.github`](https://github.com/ComPWA/ampform/blob/main/.github) folder. All +checks performed for each PR have to pass before the PR can be merged. ## Style checks @@ -325,18 +326,21 @@ performed for each PR have to pass before the PR can be merged. Formatters are tools that automatically format source code, or some document. Naturally, this speeds up your own programming, but these tools are particularly important when {ref}`collaborating `, -because a standardized format avoids line conflicts in Git. +because a standardized format avoids line conflicts in Git and makes diffs in +code review easier to read. For the Python source code, we use [`black`](https://black.readthedocs.io) and [`isort`](https://isort.readthedocs.io). For other code, we use [Prettier](https://prettier.io). All of these formatters are "opinionated -formatters": they offer only limited configuration options as, to make +formatters": they offer only limited configuration options, as to make formatting as conform as possible. -{ref}`develop:Pre-commit` automatically strips Jupyter notebook of any output -cells. Notebook cells can be formatted with -[`jupyterlab-code-formatter`](https://jupyterlab-code-formatter.readthedocs.io). -See more info at {ref}`develop:Jupyter Notebooks`. +{ref}`develop:Pre-commit` performs some additional formatting jobs. For +instance, it formats Jupyter notebooks with +[nbQA](https://github.com/nbQA-dev/nbQA) and strips them of any output cells +with [`nbstripout`](https://github.com/kynan/nbstripout). + + ### Linting @@ -443,8 +447,7 @@ notebooks and host them on the website (see ### Documentation preview -You can quickly build the documentation from the root directory of any of the -repositories with the command: +You can quickly build the documentation with the command: ```shell tox -e doc @@ -452,7 +455,9 @@ tox -e doc :::{toggle} -Alternatively, you can run `sphinx-build` yourself as follows: +Alternatively, you can run +[`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) +yourself as follows: ```shell cd docs @@ -492,16 +497,19 @@ or just click "details" under the RTD check once you submit your PR. Sometimes it happens that your Jupyter installation does not recognize your {ref}`virtual environment `. In that case, have a look at -[these instructions](https://ipython.readthedocs.io/en/stable/install/kernel_install.html#kernels-for-different-environments) +[these instructions](https://ipython.readthedocs.io/en/stable/install/kernel_install.html#kernels-for-different-environments). ::: :::: -The [docs](https://github.com/ComPWA/ampform/tree/main/docs) folder contains a -few Jupyter notebooks. These notebooks are run and tested whenever you make a -{ref}`pull request `. If you want to improve those -notebooks, we recommend working with +The [docs](https://github.com/ComPWA/ampform/tree/main/docs) folder can also +contain Jupyter notebooks. These notebooks are rendered as HTML by +[MyST-NB](https://myst-nb.readthedocs.io). The notebooks are also run and +tested whenever you make a {ref}`pull request `, so they +also serve as **integration tests**. + +If you want to improve those notebooks, we recommend working with [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable), which is {ref}`installed with the dev requirements `. Jupyter Lab offers a nicer developer experience than the default Jupyter @@ -527,6 +535,18 @@ with: EXECUTE_NB= tox -e doclive ``` +:::{tip} + +Notebooks are automatically formatted through +{ref}`pre-commit ` (see {ref}`develop:Formatting`). If you +want to format the notebooks automatically as you're working, you can do so +with +[`jupyterlab-code-formatter`](https://jupyterlab-code-formatter.readthedocs.io), +which is automatically +{ref}`installed with the dev requirements `. + +::: + ## Collaboration The source code of all ComPWA repositories is maintained with @@ -554,7 +574,7 @@ publicly visible on GitHub are: - [Milestones](https://github.com/ComPWA/ampform/milestones?direction=asc&sort=title&state=open): way to bundle issues and PRs for upcoming releases. -- [Releases](https://github.com/ComPWA/ampform/releases) +- [Releases](https://github.com/ComPWA/ampform/releases). All of these are important for the {ref}`develop:Release flow` and therefore also serve as a way to document the framework. @@ -650,7 +670,7 @@ branch". [Epic](https://blog.zenhub.com/working-with-epics-in-github) and split up into smaller tasks. -- Before creating a pull request, run `tox`. See also {ref}`develop:Tox`. +- Before creating a pull request, run {ref}`develop:Tox`. - Also use a [conventional commit message](https://www.conventionalcommits.org) style for the PR title. This is because we follow a @@ -690,7 +710,7 @@ that were merged into the main branch since the previous tag and can be viewed and edited as a release draft if you are a member of the ComPWA organization. Each of the entries are generated from the PR titles, categorized by issue label (see configuration in -[`.github.release-drafter`](https://github.com/ComPWA/ampform/blob/main/.github/release-drafter.yml)). +[`.github/release-drafter.yml`](https://github.com/ComPWA/ampform/blob/main/.github/release-drafter.yml)). Once a release is made on GitHub for a repository with source code for a Python package, a new version is automatically published on [PyPI](https://pypi.org) @@ -716,7 +736,7 @@ configuration files of the editors. Still, where code editor settings can be shared through configuration files in the repository, we provide recommended settings for the code editor as well. -This is especially the case for [VSCode](#visual-studio-code), which we prefer. +This is especially the case for [VSCode](#visual-studio-code). :::{tip}