From fd0c6017db326f6fa382671b1ed1324ad291d47e Mon Sep 17 00:00:00 2001 From: Remco de Boer Date: Fri, 4 Sep 2020 12:39:00 +0200 Subject: [PATCH] ci!: import new developer environment (#10) * build!: switch to setuptools (setup.cfg) * ci!: enforce cspell and fix errors * ci!: remove travis * ci!: switch to GitHub Actions * ci: add GitHub release drafter * ci: add PR title+label linting * ci: add and enforce Prettier configuration * ci: add and enforce markdownlint configuration * ci: define tox environments * ci: recommend specific VSCode extension * docs!: remove ADRs * docs: update badges --- .editorconfig | 18 ++++- .github/release-drafter.yml | 26 ++++++++ .github/workflows/ci.yml | 48 ++++++++++++++ .github/workflows/linkcheck.yml | 25 +++++++ .github/workflows/pr-linting.yml | 34 ++++++++++ .github/workflows/release-drafter.yml | 14 ++++ .gitignore | 22 +++++-- .markdownlint.json | 6 ++ .pre-commit-config.yaml | 22 +++++-- .prettierignore | 1 + .prettierrc | 3 +- .readthedocs.yml | 4 +- .rstcheck.cfg | 5 -- .travis.yml | 47 ------------- .vscode/.gitignore | 1 + .vscode/extensions.json | 24 +++++++ .vscode/settings.json | 7 +- README.md | 13 ++-- adr/0000-write-introduction-to-pwa-theory.md | 3 - adr/index.rst | 16 ----- adr/template.md | 69 -------------------- commitlint.config.js | 20 ++++++ conf.py | 23 +++++-- cspell.json | 63 ++++++++++++++++++ environment.yml | 2 +- index.rst | 64 ++++++++++-------- labels.toml | 59 +++++++++++++++++ pyproject.toml | 10 +++ requirements-dev.txt | 3 - requirements.txt | 4 -- setup.cfg | 52 +++++++++++++++ setup.py | 5 ++ software/documentation.rst | 2 +- software/git/branching.rst | 42 ++++++------ software/git/commit.rst | 2 +- software/git/github.rst | 6 +- software/git/remotes.rst | 2 +- software/index.rst | 12 ++-- software/testing.rst | 2 + tox.ini | 27 ++++++++ 40 files changed, 579 insertions(+), 229 deletions(-) create mode 100644 .github/release-drafter.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/linkcheck.yml create mode 100644 .github/workflows/pr-linting.yml create mode 100644 .github/workflows/release-drafter.yml create mode 100644 .markdownlint.json create mode 100644 .prettierignore delete mode 100644 .rstcheck.cfg delete mode 100644 .travis.yml create mode 100644 .vscode/.gitignore create mode 100644 .vscode/extensions.json delete mode 100644 adr/0000-write-introduction-to-pwa-theory.md delete mode 100644 adr/index.rst delete mode 100644 adr/template.md create mode 100644 commitlint.config.js create mode 100644 cspell.json create mode 100644 labels.toml delete mode 100644 requirements-dev.txt delete mode 100644 requirements.txt create mode 100644 setup.cfg create mode 100644 setup.py create mode 100644 tox.ini diff --git a/.editorconfig b/.editorconfig index aa40651a..847704c7 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,7 +1,21 @@ root = true [*] +end_of_line = lf indent_style = space -charset = utf-8 -trim_trailing_whitespace = true insert_final_newline = true +trim_trailing_whitespace = true + +[*.{py,toml}] +indent_size = 4 + +[*.{json,xml,yaml,yml}] +indent_size = 2 + +[*.{rst,inc}] +indent_size = 2 + +# when adding words through vscode, this is the resulting output format +[cspell.json] +indent_size = 4 +insert_final_newline = false diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml new file mode 100644 index 00000000..9c7f8d57 --- /dev/null +++ b/.github/release-drafter.yml @@ -0,0 +1,26 @@ +name-template: PWA Pages $NEXT_PATCH_VERSION +tag-template: $NEXT_PATCH_VERSION + +categories: + - title: 📖 Theory + label: 📖 Theory + - title: 📖 Analysis + label: 📖 Analysis + - title: 📖 Software + label: 📖 Software + - title: 🔨 Internals + labels: + - 🖱️ DX + - 💡 Enhancement + - 🔨 Maintenance + +change-template: "- $TITLE (#$NUMBER)" +sort-direction: ascending +template: | + # Release $NEXT_PATCH_VERSION + + $CHANGES + + ## Contributors since [$PREVIOUS_TAG](https://github.com/ComPWA/PWA-pages/releases/tag/$PREVIOUS_TAG) + + $CONTRIBUTORS diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..87b93293 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,48 @@ +# cspell:ignore markdownlint + +name: CI + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + documentation: + name: Build and check documentation + 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 + - name: Build HTML-pages + 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 .[dev] + sudo npm install -g cspell markdownlint-cli + - name: Perform style checks + run: tox -e sty + - name: Check spelling + run: cspell $(git ls-files) + - name: Lint Markdown files + run: markdownlint . diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml new file mode 100644 index 00000000..874658a7 --- /dev/null +++ b/.github/workflows/linkcheck.yml @@ -0,0 +1,25 @@ +name: Linkcheck + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + style: + name: Check external links + 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 + - name: Check external links + run: make linkcheck diff --git a/.github/workflows/pr-linting.yml b/.github/workflows/pr-linting.yml new file mode 100644 index 00000000..e375e66a --- /dev/null +++ b/.github/workflows/pr-linting.yml @@ -0,0 +1,34 @@ +# cspell:ignore agilepathway commitlint kode + +name: PR linting +on: + pull_request: + types: + - edited + - labeled + - opened + - reopened + - synchronize + - unlabeled + +jobs: + check-labels: + name: Check labels + runs-on: ubuntu-latest + steps: + - uses: docker://agilepathway/pull-request-label-checker:latest + with: + any_of: | + Bug,💡 Enhancement,📝 Docs,🔨 Maintenance,🖱️ DX,📖 Analysis, + 📖 Software,📖 Theory + none_of: Epic,❌ Won't fix,💫 Good first issue + repo_token: ${{ secrets.GITHUB_TOKEN }} + + check-title: + name: Check title + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Install Dependencies + run: npm install @commitlint/config-conventional + - uses: JulienKode/pull-request-name-linter-action@v0.1.2 diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml new file mode 100644 index 00000000..17fdb961 --- /dev/null +++ b/.github/workflows/release-drafter.yml @@ -0,0 +1,14 @@ +name: Release Drafter + +on: + push: + branches: + - master + +jobs: + update_release_draft: + runs-on: ubuntu-latest + steps: + - uses: release-drafter/release-drafter@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 803aa9a7..fa95db97 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,19 @@ -# Build folders -build/ +# Temporary files +.ipynb_checkpoints/ +condaenv.* -# Visual Studio Code -*.code-workspace +# Build files +*.egg-info/ +*build/ +.fuse_* +dist/ +htmlcov/ +version.py + +# Virtual environments +*venv/ +.tox/ + +# Settings +**.code-workspace +.idea/ diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..453eed2e --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,6 @@ +{ + "MD026": { "punctuation": ".,;:。，；：！" }, + "MD033": { + "allowed_elements": ["br"] + } +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b678099c..86ddb033 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,22 +1,36 @@ repos: + - repo: meta + hooks: + - id: check-hooks-apply + - id: check-useless-excludes + - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v3.1.0 + rev: v3.2.0 hooks: + - id: check-ast - id: check-case-conflict + - id: check-docstring-first + - id: check-json + - id: check-merge-conflict + - id: check-toml + - id: check-vcs-permalinks + - id: check-yaml + - id: debug-statements - id: end-of-file-fixer + exclude: cspell.json - id: mixed-line-ending - - id: requirements-txt-fixer - id: trailing-whitespace - repo: https://github.com/psf/black - rev: 19.10b0 + rev: 20.8b1 hooks: - id: black - repo: https://github.com/prettier/prettier - rev: 2.0.5 + rev: 2.1.1 hooks: - id: prettier + language_version: 12.18.2 # prettier does not specify node correctly - repo: local hooks: diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000..5c5d70c8 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +cspell.json diff --git a/.prettierrc b/.prettierrc index 5b5bd993..3b0c9fc8 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,3 +1,4 @@ { - "proseWrap": "always" + "proseWrap": "always", + "printWidth": 79 } diff --git a/.readthedocs.yml b/.readthedocs.yml index c56fd701..53ad4d48 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -2,6 +2,7 @@ version: 2 sphinx: configuration: conf.py + fail_on_warning: false formats: - htmlzip @@ -9,4 +10,5 @@ formats: python: version: 3.7 install: - - requirements: requirements.txt + - method: pip + path: .[doc] diff --git a/.rstcheck.cfg b/.rstcheck.cfg deleted file mode 100644 index 3d23ceb1..00000000 --- a/.rstcheck.cfg +++ /dev/null @@ -1,5 +0,0 @@ -[rstcheck] -ignore_roles = - cite, -ignore_directives = - bibliography, diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 4c025c3d..00000000 --- a/.travis.yml +++ /dev/null @@ -1,47 +0,0 @@ -language: python -os: linux -dist: bionic - -branches: - only: - - master - - /\d+\.\d+.*/ - -install: - - pip3 install -r requirements.txt - - pip3 install . - -before_script: - - sudo apt-get -y install pandoc - -script: - - make linkcheck - - make html - -jobs: - include: - - name: "Style checks" - python: 3.7 - script: - - pip3 install -r requirements-dev.txt - - pre-commit run -a - - - name: "Python 3.6 on Ubuntu 18.04" - python: 3.6 - - - name: "Python 3.7 on Ubuntu 18.04" - python: 3.7 - - - name: "Python 3.8 on Ubuntu 18.04" - python: 3.8 - - - name: "Python 3.7 on macOS (xcode11.2)" - os: osx - osx_image: xcode11.2 - addons: - homebrew: - update: false - packages: - - pandoc - language: shell - before_script: echo diff --git a/.vscode/.gitignore b/.vscode/.gitignore new file mode 100644 index 00000000..702ebda2 --- /dev/null +++ b/.vscode/.gitignore @@ -0,0 +1 @@ +.ropeproject diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000..ffef89f1 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,24 @@ +{ + "recommendations": [ + "bungcip.better-toml", + "christian-kohler.path-intellisense", + "davidanson.vscode-markdownlint", + "eamodio.gitlens", + "editorconfig.editorconfig", + "esbenp.prettier-vscode", + "github.vscode-pull-request-github", + "joaompinto.vscode-graphviz", + "lextudio.restructuredtext", + "ms-python.python", + "ms-vsliveshare.vsliveshare", + "redhat.vscode-yaml", + "ryanluker.vscode-coverage-gutters", + "stkb.rewrap", + "streetsidesoftware.code-spell-checker", + "travisillig.vscode-json-stable-stringify", + "trentrand.git-commit-helper-vscode", + "tyriar.sort-lines", + "yzhang.markdown-all-in-one" + ], + "unwantedRecommendations": ["dbaeumer.vscode-eslint"] +} diff --git a/.vscode/settings.json b/.vscode/settings.json index bbd08497..e87c3832 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,7 @@ { + "[json]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, "[jsonc]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }, @@ -8,7 +11,9 @@ "[yaml]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }, - "cSpell.language": "en-US", + "cSpell.customFolderDictionaries": ["cspell.json"], + "cSpell.enabled": true, + "editor.formatOnSave": true, "editor.rulers": [80], "files.associations": { "*.inc": "restructuredtext" diff --git a/README.md b/README.md index f48ab183..9a56e5a4 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ -[![Travis CI](https://travis-ci.com/ComPWA/PWA-pages.svg?branch=master)](https://travis-ci.com/ComPWA/PWA-pages) +# Welcome to the Partial Wave Analysis pages! + ![Documentation build status](https://readthedocs.org/projects/pwa/badge/?version=latest) -![pre-commit enabled](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white) +[![GPLv3+ license](https://img.shields.io/badge/License-GPLv3+-blue.svg)](https://www.gnu.org/licenses/gpl-3.0-standalone.html) +
+[![CI status](https://github.com/ComPWA/PWA-pages/workflows/CI/badge.svg)](https://github.com/ComPWA/PWA-pages/actions?query=branch%3Amaster+workflow%3ACI) +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)](https://github.com/pre-commit/pre-commit) +[![Prettier](https://camo.githubusercontent.com/687a8ae8d15f9409617d2cc5a30292a884f6813a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64655f7374796c652d70726574746965722d6666363962342e7376673f7374796c653d666c61742d737175617265)](https://prettier.io/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -# Welcome to the Partial Wave Analysis pages! - This repository contains the source code for the -[pwa.readthedocs.io](https://pwa.readthedocs.io/) pages. +[pwa.rtfd.io](https://pwa.readthedocs.io/) pages. diff --git a/adr/0000-write-introduction-to-pwa-theory.md b/adr/0000-write-introduction-to-pwa-theory.md deleted file mode 100644 index 80378fa0..00000000 --- a/adr/0000-write-introduction-to-pwa-theory.md +++ /dev/null @@ -1,3 +0,0 @@ -# [ADR-0000] Write introduction and overview to Partial Wave Analysis - -Status: **proposed** diff --git a/adr/index.rst b/adr/index.rst deleted file mode 100644 index a7fb754a..00000000 --- a/adr/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Architectural Decision Log -========================== - -This log lists the architectural decisions for `ComPWA/PWA-Pages -`_: - -.. toctree:: - :glob: - :maxdepth: 1 - - * - -For new ADRs, please use :download:`template.md` as basis. More information on -MADR is available at `adr.github.io/madr `_. -General information about architectural decision records is available at -`adr.github.io `_. diff --git a/adr/template.md b/adr/template.md deleted file mode 100644 index 5d4c99e3..00000000 --- a/adr/template.md +++ /dev/null @@ -1,69 +0,0 @@ -# [ADR-xxxx] - -Status: **[proposed | rejected | accepted | deprecated | … | superseded by -[ADR-xxxx](xxxx-example.md)]** - -Deciders: [list everyone involved in the decision] - -Technical Story: [description | ticket/issue URL] - -## Context and Problem Statement - -[Describe the context and problem statement, e.g., in free form using two to -three sentences. You may want to articulate the problem in form of a question.] - -## Decision Drivers - -- [driver 1, e.g., a force, facing concern, …] -- [driver 2, e.g., a force, facing concern, …] -- … - -## Considered Options - -- [option 1] -- [option 2] -- [option 3] -- … - -## Decision Outcome - -Chosen option: "[option 1]", because [justification. e.g., only option, which -meets k.o. criterion decision driver | which resolves force force | … | comes -out best (see below)]. - -### Positive Consequences - -- [e.g., improvement of quality attribute satisfaction, follow-up decisions - required, …] -- … - -### Negative Consequences - -- [e.g., compromising quality attribute, follow-up decisions required, …] -- … - -## Pros and Cons of the Options - -### [option 1] - -[example | description | pointer to more information | …] - -- Good, because [argument a] -- Good, because [argument b] -- Bad, because [argument c] -- … - -### [option 2] - -[example | description | pointer to more information | …] - -- Good, because [argument a] -- Good, because [argument b] -- Bad, because [argument c] -- … - -## Links - -- [Link type][link to adr] - -- … diff --git a/commitlint.config.js b/commitlint.config.js new file mode 100644 index 00000000..cb8584fd --- /dev/null +++ b/commitlint.config.js @@ -0,0 +1,20 @@ +module.exports = { + extends: ["@commitlint/config-conventional"], + rules: { + "type-enum": [ + 2, + "always", + [ + "build", + "ci", + "chore", + "docs", + "feat", + "fix", + "refactor", + "style", + "test", + ], + ], + }, +}; diff --git a/conf.py b/conf.py index c146fb17..fa659006 100644 --- a/conf.py +++ b/conf.py @@ -1,5 +1,15 @@ -# -- Project information ----------------------------------------------------- +"""Configuration file for the Sphinx documentation builder. + +This file only contains a selection of the most common options. For a full +list see the documentation: +https://www.sphinx-doc.org/en/master/usage/configuration.html +""" + +import os +import shutil +import subprocess +# -- Project information ----------------------------------------------------- project = "PWA Software Pages" copyright = "2020" author = "Common Partial-Wave Analysis" @@ -7,12 +17,12 @@ # -- General configuration --------------------------------------------------- +# The master toctree document master_doc = "index" extensions = [ - "recommonmark", + "myst_parser", "sphinx.ext.autosectionlabel", - "sphinx.ext.githubpages", "sphinx.ext.intersphinx", "sphinx_copybutton", ] @@ -30,7 +40,6 @@ ".DS_Store", "README.md", "Thumbs.db", - "adr/template.md", "build", ] @@ -41,7 +50,11 @@ # Settings for intersphinx intersphinx_mapping = { - "compwa": ("https://pwa.readthedocs.io/projects/compwa/en/latest/", None), + "ComPWA": ("https://pwa.readthedocs.io/projects/compwa/en/latest/", None), + "expertsystem": ( + "https://pwa.readthedocs.io/projects/expertsystem/en/latest/", + None, + ), "pycompwa": ("https://compwa.github.io/", None), "tensorwaves": ( "https://pwa.readthedocs.io/projects/tensorwaves/en/latest/", diff --git a/cspell.json b/cspell.json new file mode 100644 index 00000000..dbeb4f12 --- /dev/null +++ b/cspell.json @@ -0,0 +1,63 @@ +{ + "version": "0.1", + "enableFiletypes": [ + "git-commit", + "jupyter", + "xml" + ], + "flagWords": [ + "colour", + "comparision", + "favour", + "flavour", + "hte", + "optimise", + "paramater", + "parmater" + ], + "ignorePaths": [ + "*.rst_t", + "*.svg", + ".gitignore", + ".pre-commit-config.yaml", + ".pylintrc", + ".readthedocs.yml", + ".vscode/*", + ".vscode/.gitignore", + "Makefile", + "_templates/*", + "commitlint.config.js", + "conf.py", + "cspell.json", + "pyproject.toml", + "setup.cfg", + "setup.py", + "tox.ini" + ], + "language": "en-US", + "words": [ + "blazingly", + "conda", + "jupyter", + "unstaged" + ], + "ignoreWords": [ + "apidoc", + "autopep", + "htmlcov", + "linkcheck", + "markdownlint", + "maxdepth", + "mkdir", + "nbstripout", + "oneline", + "pandoc", + "pycompwa", + "pypi", + "pytest", + "rebased", + "rtfd", + "setuptools", + "toctree" + ] +} \ No newline at end of file diff --git a/environment.yml b/environment.yml index a80124ea..e82e7dc1 100644 --- a/environment.yml +++ b/environment.yml @@ -6,4 +6,4 @@ dependencies: - python>=3.6 - pip - pip: - - -r requirements.txt + - .[dev] diff --git a/index.rst b/index.rst index b7619e08..39e49f0e 100644 --- a/index.rst +++ b/index.rst @@ -1,35 +1,51 @@ -.. image:: https://travis-ci.com/ComPWA/PWA-pages.svg?branch=master - :alt: Travis CI - :target: https://travis-ci.com/ComPWA/PWA-pages +Welcome to the Partial Wave Analysis pages! +=========================================== -.. image:: https://readthedocs.org/projects/pwa/badge/?version=latest - :alt: Documentation build status - :target: https://pwa.readthedocs.io +.. list-table:: -.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white - :target: https://github.com/pre-commit/pre-commit - :alt: pre-commit + * - .. image:: https://readthedocs.org/projects/pwa/badge/?version=latest + :alt: Documentation build status + :target: https://pwa.readthedocs.io -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :alt: Code style: black - :target: https://github.com/psf/black + .. 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://github.com/ComPWA/PWA-pages/workflows/CI/badge.svg + :alt: CI status + :target: https://github.com/ComPWA/PWA-pages/actions?query=branch%3Amaster+workflow%3A%22CI%22 -Welcome to the Partial Wave Analysis pages! -=========================================== + .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white + :target: https://github.com/pre-commit/pre-commit + :alt: pre-commit + + .. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :alt: Code style: black + :target: https://github.com/psf/black -.. note:: + .. image:: https://camo.githubusercontent.com/687a8ae8d15f9409617d2cc5a30292a884f6813a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64655f7374796c652d70726574746965722d6666363962342e7376673f7374796c653d666c61742d737175617265 + :alt: Code style: Prettier + :target: https://prettier.io + +.. warning:: These pages and are **under development**. The PWA Software Pages serve two purposes: -1. They aim to bring together the many Partial Wave Analysis frameworks out there on the market through interlinked documentation. +1. They aim to bring together the many Partial Wave Analysis frameworks out + there on the market through interlinked documentation. -2. They provide a dynamic platform to collect and maintain knowledge on both PWA theory and software tools. +2. They provide a dynamic platform to collect and maintain knowledge on both + PWA theory and software tools. -As such, the pages consist two main components: :doc:`theory ` and :doc:`software `. The theory pages 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 software pages serve as a guide through the available software tools that are relevant to PWA software development. +As such, the pages consist two main components: :doc:`theory ` +and :doc:`software `. The theory pages 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 +software pages serve as a guide through the available software tools that are +relevant to PWA software development. Currently, sub-projects of the PWA Pages are: @@ -38,7 +54,9 @@ Currently, sub-projects of the PWA Pages are: * `ComPWA `_ * `pycompwa `_ -Want to contribute or be part of this collection of PWA documentation platforms? Welcome to contact the `Common Partial Wave Analysis `_ organization! +Want to contribute or be part of this collection of PWA documentation +platforms? Welcome to contact the `Common Partial Wave Analysis +`_ organization! .. toctree:: :maxdepth: 2 @@ -46,9 +64,3 @@ Want to contribute or be part of this collection of PWA documentation platforms? theory/index software/index - -.. toctree:: - :maxdepth: 1 - :hidden: - - adr/index diff --git a/labels.toml b/labels.toml new file mode 100644 index 00000000..6ad16d8b --- /dev/null +++ b/labels.toml @@ -0,0 +1,59 @@ +[Bug] +color = "e11d21" +name = "Bug" +description = "Something isn't working" + +[Epic] +color = "3E4B9E" +name = "Epic" +description = "" + +["⚪ Duplicate"] +color = "cfd3d7" +name = "⚪ Duplicate" +description = "This issue or pull request already exists" + +["❌ Won't fix"] +color = "ffffff" +name = "❌ Won't fix" +description = "This will not be worked on" + +["❔ Question"] +color = "88506B" +name = "❔ Question" +description = "Discuss this matter in the team" + +["💡 Enhancement"] +color = "c2e0c6" +name = "💡 Enhancement" +description = "New feature or improvement of existing code" + +["💫 Good first issue"] +color = "F4EAEF" +name = "💫 Good first issue" +description = "Good for newcomers" + +["📖 Analysis"] +color = "FBE2BD" +name = "📖 Analysis" +description = "About HEP analysis techniques" + +["📖 Software"] +color = "FDF3E4" +name = "📖 Software" +description = "About software development" + +["📖 Theory"] +color = "F7C57B" +name = "📖 Theory" +description = "About PWA theory" + +["🔨 Maintenance"] +color = "FFCD8F" +name = "🔨 Maintenance" +description = "Refactoring or redesign" + +["🖱️ DX"] +color = "fef2c0" +name = "🖱️ DX" +description = "Improvements to the Developer Experience" diff --git a/pyproject.toml b/pyproject.toml index 71527876..cddd0cae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,13 @@ +[build-system] +requires = [ + "setuptools>=30.3.0", + "setuptools_scm", + "wheel", +] + +[tool.setuptools_scm] +write_to = "version.py" + [tool.black] line-length = 79 target-version = [ diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index dbc65ac6..00000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,3 +0,0 @@ -black>=19.10b0 -pre-commit==2.2.0 -rstcheck diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 77051b18..00000000 --- a/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -recommonmark>=0.6 -sphinx==2.4.4 -sphinx-copybutton -sphinx_rtd_theme diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 00000000..19fccc62 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,52 @@ +[metadata] +name = PWA-pages +long_description = file: README.md +long_description_content_type = text/markdown +url = https://github.com/ComPWA/PWA-pages +license = GPLv3 or later +keywords = + HEP + PWA + amplitude analysis + partial wave analysis + particle physics + particles + physics +classifiers = + Development Status :: 1 - Planning + Intended Audience :: Developers + Intended Audience :: Education + Intended Audience :: Science/Research + License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) + Natural Language :: English + Operating System :: OS Independent + Programming Language :: Python + Topic :: Scientific/Engineering + Topic :: Scientific/Engineering :: Physics + +[options] +setup_requires = + setuptools_scm + +[options.extras_require] +doc = + doc8==0.8.1 + myst-parser==0.12.8 + nbsphinx==0.7.1 + Sphinx==3.2.1 + sphinx-copybutton==0.3.0 + sphinx-rtd-theme==0.5.0 +dev = + %(doc)s + black==20.8b1 + labels==20.1.0 + pre-commit==2.7.1 + rstcheck==3.3.1 + tox==3.20.0 + +[rstcheck] +ignore_directives = + bibliography, +ignore_roles = + cite, +report=warning diff --git a/setup.py b/setup.py new file mode 100644 index 00000000..caca1c7f --- /dev/null +++ b/setup.py @@ -0,0 +1,5 @@ +# noqa + +from setuptools import setup + +setup(use_scm_version=True) diff --git a/software/documentation.rst b/software/documentation.rst index 33580060..7b68bfe3 100644 --- a/software/documentation.rst +++ b/software/documentation.rst @@ -35,7 +35,7 @@ following extensions: `_ * `ruler `_ -* `sphellchecker +* `spellchecker `_ diff --git a/software/git/branching.rst b/software/git/branching.rst index d1812e51..dfb09112 100644 --- a/software/git/branching.rst +++ b/software/git/branching.rst @@ -1,3 +1,5 @@ +.. cspell:ignore Git's + Trying out different ideas: branching ------------------------------------- @@ -42,28 +44,28 @@ branch, run: .. code-block:: shell - git checkout new_idea + git checkout new_idea .. sidebar:: Checkout ambiguity - The :command:`git checkout` command is a tricky one: it `functions - differently depending on context - `_. In the - context of the examples here, :command:`git checkout` does two things: it - (1) tries to unpack the files of the branch to which you try to switch to - the working directory and, (2) if that succeeds, moves the ``HEAD`` to that - other branch. In this context, :command:`git checkout` is a safe to use: - Git will warn you and abort the checkout if the unpacking were to overwrite - *modified* files. - - Imagine, however, that you have modified :file:`file1.txt` and left it - unstaged. If you now run :command:`git checkout file1.txt`, Git would - overwrite :file:`file1.txt` with the version of the latest commit to the - current branch **without warning**. The behaviour is completely different - than before: Git doesn't move ``HEAD`` either. To address the confusion, - the Git developers `introduced two new commands - `_, but - checkout remains most commonly used. + The :command:`git checkout` command is a tricky one: it `functions + differently depending on context + `_. In the + context of the examples here, :command:`git checkout` does two things: it (1) + tries to unpack the files of the branch to which you try to switch to the + working directory and, (2) if that succeeds, moves the ``HEAD`` to that other + branch. In this context, :command:`git checkout` is a safe to use: Git will + warn you and abort the checkout if the unpacking were to overwrite *modified* + files. + + Imagine, however, that you have modified :file:`file1.txt` and left it + unstaged. If you now run :command:`git checkout file1.txt`, Git would + overwrite :file:`file1.txt` with the version of the latest commit to the + current branch **without warning**. The behavior is completely different than + before: Git doesn't move ``HEAD`` either. To address the confusion, the Git + developers `introduced two new commands + `_, but checkout + remains most commonly used. In this case, all this command did, was let the ``HEAD`` point to the ``new_idea`` branch. Remember that the ``HEAD`` represents the state of the @@ -165,7 +167,7 @@ can even just run :command:`git merge --abort` to land back safely in the untouched ``master`` branch! Here, let's just remove all lines but for "some content" (the ``master``) and -safe the file. Then it's a matter of staging the modifed :file:`file1.txt` and +safe the file. Then it's a matter of staging the modified :file:`file1.txt` and creating a new **merge commit**. This time, we commit the :command:`-m` message flag for the :command:`git commit` command. Git will launch `vi `_ with a pre-generated merge message. Just diff --git a/software/git/commit.rst b/software/git/commit.rst index 842e5aae..a3ef4059 100644 --- a/software/git/commit.rst +++ b/software/git/commit.rst @@ -96,7 +96,7 @@ condense overview with an abbreviated SHA-1. Here it's ``e41a065`` and It's important to realize that the Git repository now contains *three files*: an empty :file:`file1.txt` in the first commit, a :file:`file1.txt` with "some content" in the second commit, and empty :file:`file2.txt` in both commits. -This is the core of version control: Git has organised these three file +This is the core of version control: Git has organized these three file versions in two 'snapshot' commits and has recorded how the files in those commits relate to each other. diff --git a/software/git/github.rst b/software/git/github.rst index f6153491..15b32cd6 100644 --- a/software/git/github.rst +++ b/software/git/github.rst @@ -22,7 +22,7 @@ contribute: 1. Log into GitHub with your account and fork the ComPWA repository 2. Get a local copy of repository: |br| - ``git clone git@github.com:YOURACCOUNT/pycompwa.git`` |br| + ``git clone git@github.com:YOUR_ACCOUNT/pycompwa.git`` |br| (this uses the SSH protocol, so you need to `set your SSH keys `_ first) @@ -69,7 +69,7 @@ can your contributions be added main repository through a `pull request + Mark them as resolved ``git add `` + Continue the rebase ``git rebase --continue`` * Push your changes to your fork: |br| - ``git push origin `` |br| + ``git push origin `` |br| This step 'synchronizes' your local branch and the branch in your fork. It is not required after every commit, but it is certainly necessary once you are ready to merge your code into ``upstream``. @@ -83,7 +83,7 @@ can your contributions be added main repository through a `pull request .. tip:: It can be useful to push your local branch to your fork under a different name using: |br| - ``git push origin :`` + ``git push origin :`` Once you think your contribution is finished and can be merged into the main repository: diff --git a/software/git/remotes.rst b/software/git/remotes.rst index b14e8d3a..8b9fc0d3 100644 --- a/software/git/remotes.rst +++ b/software/git/remotes.rst @@ -55,6 +55,6 @@ local branches. If you checkout a remote branch, Git therefore only creates a local copy of that remote branch. You can add an arbitrary number of remotes. In a team project, it's common to -have one main repository (here `github.com/CompWA/Compwa +have one main repository (here `github.com/CompWA/ComPWA `_) that you add as a remote named ``upstream``: diff --git a/software/index.rst b/software/index.rst index bf4bc42d..4ed1f610 100644 --- a/software/index.rst +++ b/software/index.rst @@ -2,10 +2,10 @@ PWA Software Development ======================== .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - git - documentation - python - testing - tips + git + documentation + python + testing + tips diff --git a/software/testing.rst b/software/testing.rst index faa6bfd1..cb910d4f 100644 --- a/software/testing.rst +++ b/software/testing.rst @@ -1,3 +1,5 @@ +.. cspell:ignore pycompwa's + Unit testing ------------ diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..15a7da61 --- /dev/null +++ b/tox.ini @@ -0,0 +1,27 @@ +[tox] +passenv = PYTHONPATH +skip_install = True +skip_missing_interpreters=true +skipsdist = True +envlist = + doc, + sty, + +; Allows to quickly build html with `tox -e doc` from the root dir +[testenv:doc] +whitelist_externals = + make +commands = + make html + +[testenv:linkcheck] +whitelist_externals = + make +commands = + make linkcheck + +[testenv:sty] +whitelist_externals = + pre-commit +commands = + pre-commit run {posargs} -a