Improve developer environment

Created by: redeboer

This issue serves more as an epic to outline what changes I have in mind, so that the purpose of the (upcoming) PRs is clearer.

• Formatting Additional formatters can easily be implemented through pre-commit (since #2). It's easy to add some configurations, but, as with #2, it is best if @jiangyi15 does the actual formatting (to keep the commits attributed to him as the original developer). For the ComPWA repositories, we have good experience with:
  • black --> #2
  • isort (sort imports) --> #5
  • Prettier (for YAML, JSON, shell scripts, shell scripts, and Markdown) --> #6
  • nbstripout (remove cell output from notebooks, which is better for Git) --> #6
  • Several additional pre-commit hooks: https://pre-commit.com/hooks.html --> #6
• Documentation (Read the Docs)
  • Automatically generate the API with sphinx-apidoc --> #7
  • Make more heavy use of intersphinx. This is both to help the reader when navigating through the site, as well as to inform us when documentation becomes outdated (see linkcheck).--> #7
  • Run the linkcheck builder in the CI. This forces us to keep the documentation up to date --> #7
  • Implement rstcheck and doc8 through pre-commit. These are linters for reStructuredText. --> #7
  • Activate the nitpicky option and fix linking errors in the documentation.
  • Put installation and contribute instructions on the RTD pages as well.
  • Write usage instructions in terms of Jupyter notebooks and run them in the CI and on RTD (nbsphinx). This way, you (1) make sure that the instructions remain up-to-date and (2) cell output is nicely rendered on the web pages.
• Linters These are the most complicated ones, as they often require some refactoring of the code. I therefore don't intend on implementing them any time soon.
  • Enforce pylint through pre-commit. Currently pylint is only run in the CI and only generates warnings. --> #8
  • flake8 as well as several additional extensions
  • pydocstyle: my experience is that it is more configurable than other linters that check docstrings.
  • mypy: would be a bigger decision actually, because this would mean supplying type hints everywhere
• Automate: allow the developer to run all CI checks locally as well through tox

I also have some ideas for GitHub (release drafter etc), but that can be done another time.