diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml index ec97c507..8115518e 100644 --- a/.github/workflows/cd.yml +++ b/.github/workflows/cd.yml @@ -8,36 +8,6 @@ on: - "[0-9]+.[0-9]+.[0-9]+*" jobs: - test: - name: Run pytest - if: startsWith(github.ref, 'refs/tags') - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: - - macos-10.15 - - ubuntu-18.04 - python-version: [3.6, 3.7, 3.8] - exclude: - - os: macos-10.15 - python-version: 3.6 - - os: macos-10.15 - python-version: 3.8 - steps: - - uses: actions/checkout@v2 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 - with: - python-version: ${{ matrix.python-version }} - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install .[test] - - name: Test with pytest - env: - PYTEST_RUN_SLOW_TESTS: YES - run: pytest -n auto - documentation: name: Build documentation and run notebooks if: startsWith(github.ref, 'refs/tags') @@ -75,7 +45,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[dev] + pip install .[ci] sudo npm install -g cspell markdownlint-cli pyright - name: Perform style checks run: tox -e sty @@ -93,7 +63,6 @@ jobs: needs: - documentation - style - - test steps: - uses: actions/checkout@master - name: Push to stable branch diff --git a/.github/workflows/ci-epic.yml b/.github/workflows/ci-epic.yml new file mode 100644 index 00000000..3f58caff --- /dev/null +++ b/.github/workflows/ci-epic.yml @@ -0,0 +1,44 @@ +name: CI for epics + +on: + push: + branches: + - epic/* + pull_request: + branches: + - epic/* + +jobs: + documentation: + name: Build documentation and run notebooks + runs-on: ubuntu-18.04 + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.7 + uses: actions/setup-python@v2 + with: + python-version: 3.7 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install .[doc] + sudo apt-get -y install pandoc graphviz + - name: Build documentation and run notebooks + working-directory: docs + run: make html + + style: + name: Style checks + runs-on: ubuntu-18.04 + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.7 + uses: actions/setup-python@v2 + with: + python-version: 3.7 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install .[ci] + - name: Perform style checks + run: tox -e sty diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dd6c4038..d089da2f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,7 +46,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[dev] + pip install .[ci] sudo npm install -g cspell markdownlint-cli pyright - name: Perform style checks run: tox -e sty diff --git a/.github/workflows/pr-linting.yml b/.github/workflows/pr-linting.yml index e375e66a..2a168425 100644 --- a/.github/workflows/pr-linting.yml +++ b/.github/workflows/pr-linting.yml @@ -21,7 +21,7 @@ jobs: any_of: | Bug,πŸ’‘ Enhancement,πŸ“ Docs,πŸ”¨ Maintenance,πŸ–±οΈ DX,πŸ“– Analysis, πŸ“– Software,πŸ“– Theory - none_of: Epic,❌ Won't fix,πŸ’« Good first issue + none_of: ❌ Won't fix,πŸ’« Good first issue repo_token: ${{ secrets.GITHUB_TOKEN }} check-title: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f765aeb3..448ea360 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,23 +25,6 @@ repos: - id: mixed-line-ending - id: trailing-whitespace - - repo: https://github.com/psf/black - rev: 20.8b1 - hooks: - - id: black - - - repo: https://github.com/PyCQA/doc8 - rev: 0.8.1 - hooks: - - id: doc8 - args: ["-q"] - - - repo: https://github.com/kynan/nbstripout - rev: 0.3.8 - hooks: - - id: nbstripout - files: ".ipynb" - - repo: https://github.com/prettier/prettier rev: 2.1.2 hooks: @@ -50,6 +33,21 @@ repos: - repo: local hooks: + - id: black + name: black + entry: black + language: system + types: + - python + + - id: doc8 + name: doc8 + entry: doc8 + args: + - -q + language: system + files: \.(inc|rst)$ + - id: flake8 name: flake8 entry: flake8 @@ -71,6 +69,13 @@ repos: types: - python + - id: nbstripout + name: nbstripout + entry: nbstripout + language: system + types: + - jupyter + - id: pydocstyle name: pydocstyle entry: pydocstyle @@ -80,7 +85,10 @@ repos: - id: pylint name: pylint - entry: pylint --rcfile=.pylintrc --score=no + entry: pylint + args: + - --rcfile=.pylintrc + - --score=no language: system types: - python diff --git a/.vscode/settings.json b/.vscode/settings.json index 7334cc7e..ad0de1aa 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -12,7 +12,8 @@ "editor.defaultFormatter": "esbenp.prettier-vscode" }, "[markdown]": { - "editor.defaultFormatter": "esbenp.prettier-vscode" + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.wordWrap": "off" }, "[python]": { "editor.codeActionsOnSave": { @@ -56,6 +57,5 @@ "restructuredtext.confPath": "${workspaceFolder}/doc", "rewrap.wrappingColumn": 79, "telemetry.enableCrashReporter": false, - "telemetry.enableTelemetry": false, - "restructuredtext.confPath": "${workspaceFolder}/doc" + "telemetry.enableTelemetry": false } diff --git a/commitlint.config.js b/commitlint.config.js index cb8584fd..1bfd0417 100644 --- a/commitlint.config.js +++ b/commitlint.config.js @@ -9,6 +9,7 @@ module.exports = { "ci", "chore", "docs", + "epic", "feat", "fix", "refactor", diff --git a/cspell.json b/cspell.json index fd1a8024..611dd479 100644 --- a/cspell.json +++ b/cspell.json @@ -91,6 +91,7 @@ "mkdir", "modindex", "multiplets", + "mypy", "nbconvert", "nbformat", "nbstripout", @@ -120,6 +121,7 @@ "treiman", "unbinned", "unsrt", + "venv", "xlabel", "ylabel" ] diff --git a/docs/conf.py b/docs/conf.py index 8f6d9aff..657d5b21 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -104,6 +104,7 @@ "repository_branch": "stable", "path_to_docs": "docs", "use_edit_page_button": True, + "use_download_button": True, "use_issues_button": True, "use_repository_button": True, "launch_buttons": { @@ -113,7 +114,6 @@ "thebe": True, "thebelab": True, }, - "expand_sections": ["theory"], "theme_dev_mode": True, } html_title = "Partial Wave Analysis" @@ -155,6 +155,7 @@ # Settings for linkcheck linkcheck_anchors = False linkcheck_ignore = [ + "http://127.0.0.1:8000", r"https://isbnsearch.org/isbn/\d+", ] diff --git a/docs/develop.md b/docs/develop.md new file mode 100644 index 00000000..27c082d1 --- /dev/null +++ b/docs/develop.md @@ -0,0 +1,625 @@ + + +# Develop + +[![GitPod](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/PWA-pages) + +This page describes some of the tools and conventions followed by the PWA pages +and by {ref}`affiliated PWA software projects `. Where +possible, we use the +[source code of the PWA-pages repository](https://github.com/ComPWA/PWA-pages) +as example, because its file structure is comparable to that of the others. + +`````{tip} +To get started, simply run: + +````{tabbed} Conda +```shell +conda env create +conda activate pwa +pip install -e .[dev] +pre-commit install +``` +```` + +````{tabbed} Python venv +```shell +python3 -m venv ./venv +source ./venv/bin/activate +pip install -e .[dev] +pre-commit install +```` + +See {ref}`develop:Virtual environment` for more info. +````` + +## Local set-up + +### Virtual environment + +When developing source code, it is safest to work within a +[virtual environment](https://realpython.com/python-virtual-environments-a-primer), +so that all package dependencies and developer tools are safely contained. This +is helpful in case something goes wrong with the dependencies: just trash the +environment and recreate it. In addition, you can easily install other versions +of the dependencies, without affecting other packages you may be working on. + +Two common tools to manage virtual environments are Conda or Python's built-in +`venv`. In either case, you have to activate the environment whenever you want +to run the framework or use the developer tools. + +````{tabbed} Conda environment +[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. + +All projects {ref}`affiliated with the PWA pages ` +provide a +[Conda environment file](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) +(see e.g. {download}`the one for the PWA-pages <../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: + +```bash +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 +["editable" mode](#editable-installation), so that you can start developing +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: + +```bash +python3 -m venv ./venv +``` + +This creates a folder called {file}`venv` where all Python packages will be +contained. To activate the environment, run: + +```bash +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)): + +```bash +pip install -e . +``` +```` + +### Editable installation + +It is most convenient to work on a package if you install the it in +["editable" mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs). +This allows you to tweak the source code and try out new ideas immediately, +because the source code is considered the 'installation'. + +With `pip install`, a package can be installed in "editable" mode with the +[`--editable`](https://pip.pypa.io/en/stable/reference/pip_install/#install-editable) +flag. Simply +[clone](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository#_git_cloning) +the repository you want to work on, navigate into it, and run: + +```bash +python3 -m pip install -e . +``` + +````{toggle} +Internally, this just calls +```bash +python3 setup.py develop +``` +```` + +This will install all required dependencies for the package as well. + +### Optional dependencies + +Packages can additionally define +[optional dependencies](https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies). +With `pip install` you can install these with +['extras' syntax](https://www.python.org/dev/peps/pep-0508/#extras) (e.g. +{command}`pip install -e .[dev]`). We follow the following structure to group +optional developer dependencies: + +- {code}`doc` ― tools required to + {ref}`build documentation ` +- {code}`format` ― tools that automate formatting, such as + [black](https://black.readthedocs.io) and + [isort](https://isort.readthedocs.io) +- {code}`lint` ― tools that point out bugs, typos, and other issues, such as + [pylint](https://www.pylint.org) +- {code}`test` ― requirements for {ref}`runtime tests ` +- {code}`dev` ― contains all of the above, as well as some other helpful tools + like {ref}`Jupyter Lab `. + +All dependencies relevant for the developer (see +{ref}`develop:Automated coding conventions`) can be installed with: + +```bash +pip install -e .[dev] +``` + +We explain some of those tools in the following sections. + +````{dropdown} Node.js packages +If you have Node.js (`npm`) on your system, you can run a few additional +checks. Install these packages as follows (possibly with administrator rights): + +```bash +npm install -g cspell markdownlint-cli pyright +``` + +Note that [`pyright`](https://github.com/microsoft/pyright) requires Node.js +v12.x (see install instructions +[here](https://nodejs.org/en/download/package-manager)). +```` + +### Updating + +Whether installing extras or not, it may be that new commits in the repository +modify the dependencies. In that case, you have to rerun this command after +pulling new commits from the repository: + +```bash +git checkout master +git pull +pip install -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 +{ref}`create a new one `. + +## Automated coding conventions + +Where possible, we define and enforce our coding conventions through automated +tools, instead of describing them in documentation. These tools perform their +checks when you commit files locally (see {ref}`develop:Pre-commit`), when +{ref}`running tox `, and when you make a +{ref}`pull request `. + +The tools are configured through files such as +[`pyproject.toml`](https://github.com/ComPWA/PWA-pages/blob/master/pyproject.toml), +[`.pylintrc`](https://github.com/ComPWA/PWA-pages/blob/master/.pylintrc), and +[`tox.ini`](https://github.com/ComPWA/PWA-pages/blob/master/tox.ini), and the +workflow files under +[`.github`](https://github.com/ComPWA/PWA-pages/blob/master/.github). If you +run into persistent linting errors, this may mean we need to further specify +our conventions. In that case, it's best to +{ref}`create an issue ` or a +{ref}`pull request ` and propose a policy change that +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: + +```bash +pre-commit install +``` + +```{margin} Initializing pre-commit +The first time you run {command}`pre-commit` after installing or updating its +checks, it may take some time to initialize. +``` + +Upon committing, {command}`pre-commit` now runs a set of checks as defined in +the file +[{file}`.pre-commit-config.yaml`](https://github.com/ComPWA/PWA-pages/blob/master/.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: + +```bash +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. + +### Tox + +More thorough checks can be run in one go with the following command: + +```{margin} Running jobs in parallel +The {code}`-p` flag lets the jobs run in parallel. It also provides a nicer +overview of the progress. See {ref}`tox:parallel_mode`. +``` + +```bash +tox -p +``` + +This command will [run `pytest`](#testing), +{ref}`build the documentation `, and verify +cross-references in the documentation and the API. It's especially recommended +to **run tox before submitting a pull request!** + +More specialized {command}`tox` tests are defined in the +{download}`tox.ini <../tox.ini>` config file, under each {code}`testenv` +section. You can list all environments, along with a description of what they +do, by running: + +```bash +tox -av +``` + +### 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/PWA-pages/actions)). All checks +performed for each PR have to pass before the PR can be merged. + +## Style checks + +### Formatting + +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. + +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 +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`. + +### Linting + +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: + +- {download}`.markdownlint.json <../.markdownlint.json>` + - [markdownlint](https://github.com/DavidAnson/markdownlint) +- {download}`pyproject.toml <../pyproject.toml>` + - {ref}`black ` + - {ref}`isort ` +- {download}`pyrightconfig.json <../pyrightconfig.json>` + - [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) + - [Pyright](https://github.com/microsoft/pyright) +- {download}`setup.cfg <../setup.cfg>` + - [doc8](https://pypi.org/project/doc8) + - [mypy](http://mypy-lang.org) + - [rstcheck](https://pypi.org/project/rstcheck) +- {download}`tox.ini <../tox.ini>` + - [flake8](https://flake8.pycqa.org) + - [pydocstyle](https://pydocstyle.pycqa.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. +``` +```` + +### Spelling + +Throughout this repository, we follow American English +([en-us](https://www.andiamo.co.uk/resources/iso-language-codes)) spelling +conventions. As a tool, we use +[cSpell](https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md), +because it allows to check variable names in camel case and snake case. This +way, a spelling checker helps you avoid mistakes in the code as well! + +Accepted words are tracked through the {download}`cspell.json <../cspell.json>` +file. As with the other config files, {download}`cspell.json <../cspell.json>` +formulates our conventions with regard to spelling and can be continuously +updated while our code base develops. In the file, the `words` section lists +words that you want to see as suggested corrections, while `ignoreWords` are +just the words that won't be flagged. Try to be sparse in adding words: if some +word is just specific to one file, you can +[ignore it inline](https://www.npmjs.com/package/cspell#ignore), or you can add +the file to the `ignorePaths` section if you want to ignore it completely. + +It is easiest to use cSpell in {ref}`develop:Visual Studio Code`, through the +[Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) +extension: it provides linting, suggests corrections from the {code}`words` +section, and enables you to quickly add or ignore words through the +{file}`cspell.json` file. Alternatively, you can +[run cSpell](https://www.npmjs.com/package/cspell#installation) on the entire +code base (with {code}`cspell $(git ls-files)`), but for that your system +requires [npm](https://www.npmjs.com). + +## Testing + +The fastest way to run all tests is with the command: + +```bash +pytest -n auto +``` + +The flag {command}`-n auto` causes {code}`pytest` to +[run with a distributed strategy](https://pypi.org/project/pytest-xdist). + +````{margin} +```{tip} +In VScode, you can +visualize test coverage are covered with +[Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters). +For this you need to run {command}`pytest` with the flag +{command}`--cov-report=xml`). +``` +```` + +Try to keep test coverage high. You can compute current coverage by running + +```bash +tox -e cov +``` + +and opening {file}`htmlcov/index.html` in a browser. + +To get an idea of performance per component, run + +```bash +pytest --profile-svg +``` + +and check the stats and the {file}`prof/combined.svg` output file. + +```{dropdown} Organizing unit tests +When **unit** tests are well-organized, you avoid writing duplicate tests. In +addition, it allows you to check for coverage of specific parts of the code. + +Therefore, when writing new tests, try to follow the module and class structure +of the package. For example, put unit tests that test the functions and methods +defined of some module called {code}`package.module` module into a test file +called {file}`test_module.py` that is directly placed under the {file}`tests` +folder. Similarly, bundle for a class {code}`SomeClass` under a +{code}`TestSomeClass` class in that file and test its methods (say, +{code}`SomeClass.my_method`) with `TestSomeClass.test_my_method`. + +If possible, also try to order the tests by alphabetical order (that is, the +order of the {code}`import` statements). +``` + +```{note} +Jupyter notebooks can also be used as tests. See more info +{ref}`here `. +``` + +## Documentation + +The documentation that you find on [pwa.rtfd.io](http://pwa.rtfd.io) and its +sub-projects is built with [Sphinx](https://www.sphinx-doc.org). Sphinx also +[builds the API page](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) +of the packages and therefore checks whether the +[docstrings](https://www.python.org/dev/peps/pep-0257) in the Python source +code are valid and correctly interlinked. + +You can quickly build the documentation from the root directory of any of the +repositories with the command: + +```bash +tox -e doc +``` + +````{toggle} +Alternatively, you can run `sphinx-build` yourself as follows: + +```bash +cd docs +make html +``` +```` + +If you are doing a lot of work on the documentation, +[`sphinx-autobuild`](https://pypi.org/project/sphinx-autobuild) is a nice tool +to use. Just run: + +```bash +tox -e doc-live +``` + +This will start a server [http://127.0.0.1:8000](http://127.0.0.1:8000) where +you can continuously preview the changes you make to the documentation. + +### Documentation preview + +A nice feature of [Read the Docs](https://readthedocs.org), where we host our +documentation, is that documentation is built for each pull request as well. +This means that you can view the documentation for your changes as well. For +more info, see +[here](https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html), +or just click "details" under the RTD check once you submit your PR. + +We make use of [Markedly Structured Text](https://myst-parser.readthedocs.io) +(MyST), so you can write the documentation in either +[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +or [Markdown](https://www.markdownguide.org). In addition, it's easy to write +(interactive) code examples in Jupyter notebooks and host them on the website +(see [MyST-NB](https://myst-nb.readthedocs.io))! + +### Jupyter Notebooks + +````{margin} +```{tip} +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) +``` +```` + +The [docs](https://github.com/ComPWA/PWA-pages/tree/master/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 +[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 +notebook editor does. + +In addition, we recommend to install a few extensions: + +```bash +jupyter labextension install jupyterlab-execute-time +jupyter labextension install @ijmbarr/jupyterlab_spellchecker +jupyter labextension install @aquirdturtle/collapsible_headings +jupyter labextension install @ryantam626/jupyterlab_code_formatter +jupyter labextension install @jupyter-widgets/jupyterlab-manager + +jupyter serverextension enable --py jupyterlab_code_formatter +``` + +Now, if you want to test all notebooks in the documentation folder and check +what their output cells will look like in the {ref}`develop:Documentation`, you +can do this with: + +```bash +tox -e docnb +``` + +This command takes more time than `tox -e doc`, but it is good practice to do +this before you submit a pull request. + +## Collaboration + +The source code of all related repositories is maintained with Git and +published through GitHub. We keep track of issues with the code, documentation, +and developer set-up with GitHub issues (see for instance +[here](https://github.com/ComPWA/PWA-pages/issues)). This is also the place +where you can +[report bugs](https://github.com/ComPWA/PWA-pages/issues/new/choose). + +### Issue management + +We keep track of issue dependencies, time estimates, planning, pipeline +statuses, et cetera with [ZenHub](https://app.zenhub.com). You can use your +GitHub account to log in there and automatically get access to the issue boards +of the packages once you are part of the +[ComPWA organization](https://github.com/ComPWA). + +Publicly available are: + +- [Issue labels](https://github.com/ComPWA/PWA-pages/labels): help to + categorize issues by type (maintenance, enhancement, bug, etc.). + +- [Milestones](https://github.com/ComPWA/PWA-pages/milestones?direction=asc&sort=title&state=open): + way to bundle issues for upcoming releases. + +### Commit conventions + +- Please use + [conventional commit messages](https://www.conventionalcommits.org): start + the commit with a semantic keyword (see e.g. + [Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#type) + or + [these examples](https://seesparkbox.com/foundry/semantic_commit_messages)), + followed by [a column](https://git-scm.com/docs/git-interpret-trailers), then + the message. The message itself should be in imperative mood β€” just imagine + the commit to give a command to the code framework. So for instance: + + ```none + ci: implement coverage report tools + fix: fix typo in raised ValueError + chore: remove redundant print statements + docs!: rewrite welcome pages + ``` + +- Keep pull requests small. If the issue you try to address is too big, discuss + in the team whether the issue can be converted into an + [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:Testing`. + +- Also use a [conventional commit message](https://www.conventionalcommits.org) + style for the PR title. This is because we follow a + [linear commit history](https://docs.github.com/en/github/administering-a-repository/requiring-a-linear-commit-history) + and the PR title will become the eventual commit message. Note that a + conventional commit message style, as well as + {ref}`PR labels `, are + {ref}`enforced through GitHub Actions ` (see overview + [here](https://github.com/ComPWA/PWA-pages/actions?query=workflow%3A%22PR+linting%22)). + The corresponding configuration file is + {download}`commitlint.config.js <../commitlint.config.js>`. + +- PRs can only be merged through 'squash and merge'. There, you will see a + summary based on the separate commits that constitute this PR. Leave the + relevant commits in as bullet points. See the + [commit history](https://github.com/ComPWA/PWA-pages/commits/master) for + examples. This comes in especially handy when + {ref}`drafting a release `! + +### Milestones and releases + +Releases are managed with the +[GitHub release page](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/managing-releases-in-a-repository), +see for instance +[the one for the PWA pages](https://github.com/ComPWA/PWA-pages/releases). + +Release notes are +[automatically generated from the PRs](https://github.com/release-drafter/release-drafter) +that were merged into the master branch since the previous tag. The changelog +there is generated from the PR titles and categorized by issue label. New +releases are automatically published to PyPI when a new tag with such release +notes is created (see +[setuptools-scm](https://pypi.org/project/setuptools-scm)). + +## Code editors + +### Visual Studio code + +We recommend using [Visual Studio Code](https://code.visualstudio.com) as it's +free, regularly updated, and very flexible through it's wide offer of user +extensions. + +If you add or open this repository as a +[VSCode workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces), +the file {download}`.vscode/settings.json <../.vscode/settings.json>` will +ensure that you have the right developer settings for this repository. In +addition, VSCode will automatically recommend you to install a number of +extensions that we use when working on this code base. +[They are defined](https://code.visualstudio.com/updates/v1_6#_workspace-extension-recommendations) +in the {download}`.vscode/extensions.json <../.vscode/extensions.json>` file. + +You can still specify your own settings in +[either the user or encompassing workspace settings](https://code.visualstudio.com/docs/getstarted/settings), +as the VSCode settings that come with this are folder settings. + +````{dropdown} Conda and VSCode +Projects related to the PWA pages are best developed +{ref}`with Conda ` and VSCode. The complete +developer install procedure then becomes: + +```bash +git clone https://github.com/ComPWA/PWA-pages.git # or some other repo +cd PWA-pages +conda env create +conda activate pwa # or whatever the name is +pip install -e .[dev] +code . # open folder in VSCode +``` +```` diff --git a/docs/develop.rst b/docs/develop.rst deleted file mode 100644 index 343d9798..00000000 --- a/docs/develop.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. cSpell:ignore aquirdturtle docnb htmlcov ijmbarr labextension pylintrc -.. cSpell:ignore ryantam serverextension testenv - -Develop -======= - -.. list-table:: - - * - .. image:: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod - :alt: GitPod - :align: left - :target: https://gitpod.io/#https://github.com/ComPWA/PWA-pages - -If you have installed the `pwa_pages` in :ref:`install:Editable mode`, it is -easy to tweak the source code and try out new ideas immediately, because the -source code is considered the 'installation'. - -.. admonition:: Conda and VSCode - :class: dropdown - - The easiest way to , is by using :ref:`Conda ` and :ref:`develop:Visual Studio code`. In that case, - the complete developer install procedure becomes: - - .. code-block:: shell - - git clone https://github.com/ComPWA/PWA-pages.git - cd PWA-pages - conda env create - conda activate es - pip install -e .[dev] - code . # open folder in VSCode - - For more info, see :ref:`develop:Visual Studio code`. - - -Automated style checks ----------------------- - -When working on the source code of the `pwa_pages`, it is highly recommended to -install certain additional Python tools. Assuming you installed the `pwa_pages` -in :ref:`editable mode `, these additional tools can be -installed into your :ref:`virtual environment ` in one go: - -.. code-block:: shell - - pip install -e .[dev] - -Most of the tools that are installed with this command use specific -configuration files (e.g. `pyproject.toml -`_ for `black -`_, `.pylintrc -`_ for `pylint -`_, and `tox.ini -`__ for `flake8 -`_ and `pydocstyle `_). -These config files **define our convention policies**, such as :pep:`8`. If you -run into persistent linting errors, this may mean we need to further specify -our conventions. In that case, it's best to create an issue and propose a -policy change that can then be formulated in the config files. - -.. tip:: - :class: dropdown - - If you have Node.js (:code:`npm`) on your system, you can run a few - additional checks. Install these packages as follows (possibly with - administrator rights): - - .. code-block:: bash - - npm install -g cspell markdownlint-cli pyright - - Normally, these packages are only run in the :ref:`CI `, but if you have them installed, they are also run when you run - :ref:`tox ` (local CI). - - Note that :code:`pyright` requires Node.js v12.x (see install instructions - `here `__). - - -Pre-commit ----------- - -All **style checks** are enforced through a tool called `pre-commit -`__. This tool needs to be activated, but only once, -after you clone the repository: - -.. code-block:: shell - - pre-commit install - -Upon committing, :code:`pre-commit` now runs a set of checks as defined in the -file `.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: - -.. code-block:: shell - - pre-commit run -a - -This command is also run on GitHub actions whenever you submit a pull request, -ensuring that all files in the repository follow the conventions set in the -config files of these tools. - - -Documentation -------------- - -The documentation that you find on `pwa.rtfd.io `_ are -built from the `documentation source code folder -`_ (:file:`docs`) with -`Sphinx `_. Sphinx also `builds the API -`_ and therefore -checks whether the `docstrings `_ in -the Python source code are valid and correctly interlinked. - -You can quickly build the documentation from the root directory of this -repository with the command: - -.. code-block:: shell - - tox -e doc - -Alternatively, you can run :code:`sphinx-build` yourself as follows: - -.. code-block:: shell - - cd docs - make html # or EXECUTE_NB= make html - -A nice feature of `Read the Docs `_, where we host -our documentation, is that documentation is built for each pull request as -well. This means that you can view the documentation for your changes as well. -For more info, see `here -`__, -or just click "details" under the RTD check once you submit your PR. - -We make use of `Markedly Structured Text `_ -(MyST), so you can write the documentation in either `reStructuredText -`_ or -`Markdown `_. In addition, it's easy to write -(interactive) code examples in Jupyter notebooks and host them on the website, -(see `MyST-NB `_)! - - -Jupyter Notebooks ------------------ - -.. margin:: - - .. tip:: - Sometimes it happens that your Jupyter installation does not recognize your - :ref:`virtual environment `. - In that case, have a look at `these instructions - `__. - -The `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 `Jupyter Lab -`_, which is installed with the -:code:`dev` requirements of the `pwa_pages`. Jupyter Lab offers a nicer -developer experience than the default Jupyter notebook editor does. In -addition, we recommend to install a few extensions: - -.. code-block:: shell - - jupyter labextension install jupyterlab-execute-time - jupyter labextension install @ijmbarr/jupyterlab_spellchecker - jupyter labextension install @aquirdturtle/collapsible_headings - jupyter labextension install @ryantam626/jupyterlab_code_formatter - jupyter labextension install @jupyter-widgets/jupyterlab-manager - - jupyter serverextension enable --py jupyterlab_code_formatter - -Now, if you want to test all notebooks documentation folder and check how they -will look like in the :ref:`develop:Documentation`, you can do this with: - -.. code-block:: shell - - tox -e docnb - -This command takes more time than :code:`tox -e doc`, but it is good practice -to do this before you submit a pull request. - - -Spelling --------- - -Throughout this repository, we follow American English (`en-us -`_) spelling -conventions. As a tool, we use `cSpell -`_ -because it allows to check variable names in camel case and snake case. This -way, a spelling checker helps you in avoid mistakes in the code as well! - -Accepted words are tracked through the :file:`cspell.json` file. As with the -other config files, :file:`cspell.json` formulates our conventions with regard -to spelling and can be continuously updated while our code base develops. In -the file, the :code:`words` section lists words that you want to see as -suggested corrections, while :code:`ignoreWords` are just the words that won't -be flagged. Try to be sparse in adding words: if some word is just specific to -one file, you can `ignore it inline -`_, or you can add the file to the -:code:`ignorePaths` section if you want to ignore it completely. - -It is easiest to use cSpell in :ref:`develop:Visual Studio Code`, through -the `Code Spell Checker -`_ -extension: it provides linting, suggests corrections from the :code:`words` -section, and enables you to quickly add or ignore words through the -:file:`cspell.json` file. Alternatively, you can `run cSpell -`__ on the entire code base -(with :code:`cspell $(git ls-files)`), but for that your system requires `npm -`_. - - -Git and GitHub --------------- - -The `pwa_pages` source code is maintained with Git and published through -GitHub. We keep track of issues with the code, documentation, and developer -set-up with GitHub issues (see overview `here -`__). This is also the place where -you can `report bugs `_. - - -Issue management -^^^^^^^^^^^^^^^^ - -We keep track of issue dependencies, time estimates, planning, pipeline -statuses, et cetera with `ZenHub `_. You can use your -GitHub account to log in there and automatically get access to the `pwa_pages` -issue board once you are part of the `ComPWA organization -`_. - -Publicly available are: - -* `Issue labels `_: help to - categorize issues by type (maintenance, enhancement, bug, etc.). - -* `Milestones - `__: - way to bundle issues for upcoming releases. - - -Commit conventions -^^^^^^^^^^^^^^^^^^ - -* Please use - `conventional commit messages `_: start - the commit with a semantic keyword (see e.g. `Angular - `_ or - `these examples `_, - followed by `a column `_, - then the message. The message itself should be in imperative mood β€” just - imagine the commit to give a command to the code framework. So for instance: - :code:`feat: add coverage report tools` or :code:`fix: remove ...`. - -* Keep pull requests small. If the issue you try to address is too big, discuss - in the team whether the issue can be converted into an `Epic - `_ and split up into - smaller tasks. - -* Before creating a pull request, run :code:`tox`. See also - :ref:`develop:Testing`. - -* Also use a - `conventional commit message `_ style - for the PR title. This is because we follow a `linear commit history - `_ - and the PR title will become the eventual commit message. Note that a - conventional commit message style is `enforced through GitHub Actions - `_, - as well as :ref:`PR labels `. - -* PRs can only be merged through 'squash and merge'. There, you will see a - summary based on the separate commits that constitute this PR. Leave the - relevant commits in as bullet points. See the `commit history - `_ for examples. This - comes in especially handy when :ref:`drafting a release `! - - -Milestones and releases -^^^^^^^^^^^^^^^^^^^^^^^ - -An overview of the `pwa_pages` releases can be found on the `release page -`__. - -Release notes are automatically generated from the PRs that were merged into -the master branch since the previous tag (see `latest draft -`_). The changelog there is -generated from the PR titles and categorized by issue label. New releases are -automatically published to PyPI when a new tag with such release notes is -created (see `setuptools-scm `_). - - -Continuous Integration -^^^^^^^^^^^^^^^^^^^^^^ - -All :ref:`style checks `, testing of the -:ref:`documentation and links `, and :ref:`unit tests -` are performed upon each pull request through `GitHub Actions -`_ (see status overview `here -`__). All checks performed for -each PR have to pass before the PR can be merged. - - -Visual Studio code ------------------- - -We recommend using `Visual Studio Code `_ as -it's free, regularly updated, and very flexible through it's wide offer of user -extensions. - -If you add or open this repository as a `VSCode workspace -`_, the file -`.vscode/settings.json -`_ will -ensure that you have the right developer settings for this repository. In -addition, VSCode will automatically recommend you to install a number of -extensions that we use when working on this code base (they are `defined -`__ -in the `.vscode/extensions.json -`_ -file). - -You can still specify your own settings in `either the user or encompassing -workspace settings `_, -as the VSCode settings that come with this are folder settings. diff --git a/docs/index.md b/docs/index.md index 30c01f35..0cef6021 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,22 +4,8 @@ ``` - - -```{eval-rst} -.. list-table:: - :widths: auto - :align: left - - * - .. image:: https://img.shields.io/badge/License-GPLv3+-blue.svg - :alt: GPLv3+ license - :target: https://www.gnu.org/licenses/gpl-3.0-standalone.html - - .. image:: https://readthedocs.org/projects/pwa/badge/?version=latest - :alt: Documentation build status - :target: https://pwa.readthedocs.io -``` - - +[![GPLv3+ license](https://img.shields.io/badge/License-GPLv3+-blue.svg)](https://www.gnu.org/licenses/gpl-3.0-standalone.html) +[![Documentation build status](https://readthedocs.org/projects/pwa/badge/?version=latest)](https://pwa.readthedocs.io) ```{warning} These pages and are **under development**. @@ -35,15 +21,18 @@ The PWA Software Pages serve two purposes: As such, the pages consist three main components: [theory](./theory.rst), [analysis techniques](./analysis.rst), and [software](./software.rst). The -[theory pages](./theory.rst) are to be a collection of the basics of PWA -theory, along with references to more in-depth sources. This is useful, because -it is often difficult for newcomers to find their way around in the growing -amount of PWA literature and experimental results. The +[theory pages](./theory.rst) are to be a collection of the theoretical basis of +Partial Wave Analysis, along with references to more in-depth sources. This is +useful, because it is often difficult for newcomers to find their way around in +the growing amount of PWA literature and experimental results. The [analysis section](./analysis.rst) visits some of the common statistics techniques that you need to be familiar with to do PWA (and event selection more generally). The [software pages](./software.rst) serve as a guide through the available software tools that are relevant to PWA software development. +Finally, the [develop page](./develop.md) formulates some conventions and tools +that are used by {ref}`affiliated software packages `. + ```{toctree} --- maxdepth: 2 diff --git a/docs/software.md b/docs/software.md index e72cb082..6be67832 100644 --- a/docs/software.md +++ b/docs/software.md @@ -25,6 +25,8 @@ software/z.references ## PWA Software Packages +### Sub-projects + Currently, sub-projects of the PWA Pages are: - {doc}`TensorWaves ` @@ -33,7 +35,13 @@ Currently, sub-projects of the PWA Pages are: - {doc}`ComPWA ` - {doc}`pycompwa ` -Other PWA packages are: +Want to contribute or be part of this collection of PWA documentation +platforms? Welcome to contact the +[Common Partial Wave Analysis](https://github.com/ComPWA) organization! + +### Other PWA packages + +Some other, highly recommended PWA packages are: - [Pawian](https://panda-wiki.gsi.de/foswiki/bin/view/PWA/PawianPwaSoftware) (Ruhr-UniversitΓ€t Bochum for [PANDA](https://panda.gsi.de) / @@ -51,6 +59,6 @@ Other PWA packages are: - [GPUPWA](https://sourceforge.net/projects/gpupwa) ([BESIII](http://bes3.ihep.ac.cn)) -Want to contribute or be part of this collection of PWA documentation -platforms? Welcome to contact the -[Common Partial Wave Analysis](https://github.com/ComPWA) organization! +Please +[let us know](https://github.com/ComPWA/PWA-pages/issues/new?title=Missing%20PWA%20package) +if you have other recommendations! diff --git a/docs/software/git/branching.rst b/docs/software/git/branching.rst index eb55cb37..00938cc3 100644 --- a/docs/software/git/branching.rst +++ b/docs/software/git/branching.rst @@ -22,7 +22,7 @@ initializing a repository, Git automatically creates a branch called .. code-block:: shell - git branch + git branch There is a ``master`` branch next to the ``HEAD`` (which is in a "detached" state). The master moved along on to the second commit you made and stayed @@ -32,8 +32,8 @@ branch ``new_idea``: .. code-block:: shell - git branch new_idea - git branch -v + git branch new_idea + git branch -v The second commands prints the existing branches along with the commits they point to. You'll see that there is a ``new_idea`` branch pointing to the first @@ -81,19 +81,19 @@ them, and creating a new commit from those changes: .. code-block:: shell - echo "this content is much better!" > file1.txt - echo "from the new idea" > file2.txt - git add -A - git commit -m "fix: add content to files" + echo "this content is much better!" > file1.txt + echo "from the new idea" > file2.txt + git add -A + git commit -m "fix: add content to files" There is a nice way to visualize the current situation (so nice, in fact, that we label it): .. code-block:: shell - :caption: Visualize branching tree - :name: visualize-branches + :caption: Visualize branching tree + :name: visualize-branches - git log --graph --all --oneline + git log --graph --all --oneline This shows that there are now three commits: the initial commit, the commit to which the ``master`` branch points, and the commit to which the ``new_idea`` @@ -104,12 +104,12 @@ branch and the HEAD currently point. The dashes also nicely display that the .. code-block:: shell - mkdir folder - mv file2.txt folder/moved_file.txt - git add folder - git rm file2.txt - git status -s - git commit -m "refactor: move file" + mkdir folder + mv file2.txt folder/moved_file.txt + git add folder + git rm file2.txt + git status -s + git commit -m "refactor: move file" Notice that we used :command:`git status -s`, a nice way to summarize the situation in the working tree. In this case, it shows that :file:`file2.txt` @@ -126,8 +126,8 @@ the old ones from the ``master`` branch (but see the sidebar note). .. code-block:: shell - git checkout master - ls + git checkout master + ls Let's see what happens if we `merge `_ @@ -135,7 +135,7 @@ the ``new_idea`` branch *into* the ``master``: .. code-block:: - git merge new_idea + git merge new_idea Wow, what's this?? Git tells it is "removing :file:`file2.txt`", but then runs into a conflict for :file:`file1.txt`. Here we see that *Git does line-wise @@ -146,17 +146,17 @@ file itself and is waiting for your input. If you have a look in the file: .. code-block:: shell - vi file1.txt + vi file1.txt you'll see: .. code-block:: - <<<<<<< HEAD - this content is much better! - ======= - some content - >>>>>>> master + <<<<<<< HEAD + this content is much better! + ======= + some content + >>>>>>> master It shows that "some content" was the line from the ``master`` branch and "this content is much better!" came in from the ``HEAD`` (the ``HEAD`` was moved to @@ -175,8 +175,8 @@ as a commit message. .. code-block:: shell - git add file1.txt - git commit + git add file1.txt + git commit If we again :ref:`visualize the branch structure `, we see something cool: the "initial commit" branches off into two branches, then @@ -186,7 +186,7 @@ delete it now that the 'new idea' has been merged with the ``master``: .. code-block:: shell - git branch -d new_idea + git branch -d new_idea That's it, the fundamentals of branching! To be sure, the example here is trivial, but what makes Git so powerful is that it can handle large numbers of diff --git a/environment.yml b/environment.yml index b65aa5d4..b7a159e3 100644 --- a/environment.yml +++ b/environment.yml @@ -2,7 +2,7 @@ name: pwa-pages channels: - defaults dependencies: - - python>=3.6 + - python>=3.6,<3.9 - pip - graphviz # for binder - pip: diff --git a/setup.cfg b/setup.cfg index 7e53a633..ff513e94 100644 --- a/setup.cfg +++ b/setup.cfg @@ -59,16 +59,17 @@ doc = pybtex==0.23.0 pydeps==1.9.11 Sphinx==3.2.1 - sphinx-book-theme==0.0.38 + sphinx-book-theme==0.0.39 sphinx-copybutton==0.3.1 sphinx-math-dollar==1.2 sphinx-panels==0.5.2 sphinx-thebe==0.0.8 sphinx-togglebutton==0.2.3 sphinxcontrib-bibtex==1.0.0 -dev = - %(doc)s +format = black==20.8b1 + isort==5.6.1 +lint = data-science-types==0.2.19 doc8==0.8.1 flake8==3.8.3 # >=3 for per-file-ignores @@ -76,18 +77,27 @@ dev = flake8-bugbear==20.1.4 flake8-builtins==1.5.3 flake8-rst-docstrings==0.0.13 - isort==5.6.1 - jupyterlab==2.2.4 - jupyterlab_code_formatter==1.3.6 - jupyter_nbextensions_configurator==0.4.1 - labels==20.1.0 mypy==0.782 + nbstripout==0.3.8 pep8-naming==0.11.1 - pre-commit==2.7.1 pydocstyle==5.1.1 pylint==2.6.0 rstcheck==3.3.1 +ci = + %(format)s + %(lint)s + pre-commit==2.8.2 tox==3.20.0 +tools = + jupyterlab==2.2.4 + jupyterlab_code_formatter==1.3.6 + jupyter_nbextensions_configurator==0.4.1 + labels==20.1.0 + sphinx-autobuild==2020.9.1 +dev = + %(ci)s + %(doc)s + %(tools)s [doc8] extension=.inc @@ -120,6 +130,7 @@ ignore_directives = tabbed, thebe-button, toggle, +ignore_messages = (Error in "code-block" directive:$) ignore_roles = cite, wiki, diff --git a/tox.ini b/tox.ini index c8c5bc32..9a1cf275 100644 --- a/tox.ini +++ b/tox.ini @@ -25,6 +25,20 @@ whitelist_externals = commands = make ignore-warnings=1 linkcheck # for margin directive +[testenv:doc-live] +description = + Set up a server to preview changes to the HTML pages live +whitelist_externals = + sphinx-autobuild +commands = + sphinx-autobuild \ + --watch docs \ + --watch src \ + --re-ignore docs/api/.* \ + --re-ignore docs/_build/.* \ + --open-browser \ + docs/ docs/_build/html + [testenv:sty] description = Perform all linting, formatting, and spelling checks @@ -38,7 +52,7 @@ commands = mypy . # run separately because of potential caching problems pre-commit run {posargs} -a - bash -ec "cspell $(git ls-files)" - - bash -ec "markdownlint ." + - bash -ec "markdownlint . --ignore docs/_build" [flake8] application-import-names = pwa_pages