👷♻️ Use hatch as build backend (#204)

[Hatch](https://github.com/pypa/hatch) is the new modern python build system which out of the box comes with a package-aware venv setup system (`hatch shell` will set up the dev env).
The package is fully configured via `pyproject.toml` eliminating the need for husk only `setup.py` and the `setup.cfg` which were needed for the old `setuptools` way of installing.
One of the main advantages of this change is that `hatch` by default uses `.pth` files for editable installs which [are needed for proper static analysis and auto-completion by tools like pylance](https://github.com/microsoft/pylance-release/blob/main/TROUBLESHOOTING.md#common-questions-and-issues)
(vscode).
While there is a [workaround for `setuptools`](https://setuptools.pypa.io/en/latest/userguide/development_mode.html#legacy-behavior)
(`pip install -e . --config-settings editable_mode=compat`) that workaround is due to deprecation, so it is best to switch now.

During this refactoring of the build system the documentation file format was changed from `reStructuredText` to [myst
parser](https://myst-parser.readthedocs.io/en/latest/) flavored markdown using [`rst2myst`](https://rst-to-myst.readthedocs.io/en/latest/).
This gives us the full `rst` power as opt-in without needing to always deal `rst`.

**Note:**
For the development of `pyglotaran` **AND** `pyglotaran-extras` at the
same time (side by side), one should still use a common environment
(e.g. conda env) with `pip install -e .` instead of `hatch shell`. But
`hatch shell` is a convenient way to develop against the latest stable
version of `pyglotaran` without creating a dedicated global env.

### Change summary

- [👷 Use hatch as build
backend](f117a43)
- [🧹 Cleanup old installation
residuals](5107828)
- [📚👌 Convert docs from RST to
MD](eca6588)

.github/workflows/autoupdate-pre-commit-config.yml

@@ -17,10 +17,12 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - uses: actions/cache@v3
         with:
           path: ~/.cache/pre-commit
           key: pre-commit-autoupdate
+
       - name: Update pre-commit config packages
         uses: technote-space/create-pr-action@v2
         with:

.github/workflows/integration-tests.yml

@@ -32,20 +32,24 @@ jobs:
         example_name: ${{fromJson(needs.create-example-list.outputs.example-list)}}
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Install pyglotaran-extras
         run: |
           pip install wheel
           pip install .
+
       - name: ${{ matrix.example_name }}
         id: example-run
         uses: glotaran/pyglotaran-examples@main
         with:
           example_name: ${{ matrix.example_name }}
           install_extras: false
+
       - name: Upload Example Plots Artifact
         uses: actions/upload-artifact@v3
         with:

.github/workflows/test.yml

@@ -17,10 +17,12 @@ jobs:
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
+
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Run pre-commit
         uses: pre-commit/action@v3.0.0
 
@@ -30,24 +32,27 @@ jobs:
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
+
       - name: Setup conda
         uses: s-weigand/setup-conda@v1
         with:
           conda-channels: conda-forge
           activate-conda: false
+
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Install dependencies
         run: |
           conda install -y pandoc
           python -m pip install -U pip wheel
-          pip install .
-          python -m pip install -U -r docs/requirements.txt
+          python -m pip install ".[docs]"
+
       - name: Show installed dependencies
-        run: |
-          pip freeze
+        run: pip freeze
+
       - name: Build docs
         run: make --directory=docs clean html
 
@@ -57,24 +62,27 @@ jobs:
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
+
       - name: Setup conda
         uses: s-weigand/setup-conda@v1
         with:
           conda-channels: conda-forge
           activate-conda: false
+
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Install dependencies
         run: |
           conda install -y pandoc
           python -m pip install -U pip wheel
-          pip install .
-          python -m pip install -U -r docs/requirements.txt
+          python -m pip install ".[docs]"
+
       - name: Show installed dependencies
-        run: |
-          pip freeze
+        run: pip freeze
+
       - name: Build docs
         run: make --directory=docs clean linkcheck
 
@@ -90,18 +98,21 @@ jobs:
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+
       - name: Install dependencies
         run: |
           python -m pip install -U pip wheel
-          python -m pip install -U -e .
-          python -m pip install -r requirements_dev.txt
+          python -m pip install -r requirements_pinned.txt
+          python -m pip install -U -e ".[test]"
+
       - name: Run tests
-        run: |
-          py.test --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
+        run: python -m pytest --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
+
       - name: Codecov Upload
         continue-on-error: true
         uses: codecov/codecov-action@v3
@@ -117,22 +128,24 @@ jobs:
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
+
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Install dependencies
         run: |
           python -m pip install -U pip wheel
-          python -m pip install -U -e .
-          python -m pip install -r requirements_dev.txt
+          python -m pip install -r requirements_pinned.txt
+          python -m pip install -U -e ".[test]"
           python -m pip install git+https://github.com/glotaran/pyglotaran
+
       - name: Show installed dependencies
-        run: |
-          pip freeze
+        run: pip freeze
+
       - name: Run tests
-        run: |
-          py.test --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
+        run: python -m pytest --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
 
   deploy:
     name: Deploy to PyPi
@@ -141,16 +154,17 @@ jobs:
     needs: test
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
+
       - name: Install dependencies
-        run: |
-          python -m pip install -U pip wheel
+        run: python -m pip install -U hatch
+
       - name: Build dist
-        run: |
-          python setup.py sdist bdist_wheel
+        run: hatch build
 
       - name: Publish package
         uses: pypa/gh-action-pypi-publish@v1.8.10

.pre-commit-config.yaml

@@ -44,11 +44,6 @@ repos:
       - id: isort
         minimum_pre_commit_version: 2.9.0
 
-  - repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v2.4.0
-    hooks:
-      - id: setup-cfg-fmt
-
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v3.0.3 # Use the sha or tag you want to point at
     hooks:
@@ -112,7 +107,7 @@ repos:
           - "--allow-init-docstring=True"
           - "--skip-checking-short-docstrings=False"
         name: "flake8 lint docstrings"
-        exclude: "^(docs/|setup.py$|tests?/)"
+        exclude: "^(docs/|tests?/)"
         additional_dependencies: [pydoclint==0.1.4]
 
   - repo: https://github.com/rstcheck/rstcheck
@@ -121,6 +116,7 @@ repos:
       - id: rstcheck
         additional_dependencies: [sphinx]
         exclude: "^docs/_templates"
+        args: [--ignore-directives=autosummary]
 
   - repo: https://github.com/pre-commit/pygrep-hooks
     rev: v1.10.0

.taplo.toml

@@ -0,0 +1,3 @@
+[formatting]
+align_comments = false
+array_auto_collapse = false

CONTRIBUTING.md

@@ -0,0 +1,122 @@
+```{highlight} shell
+
+```
+
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at <https://github.com/glotaran/pyglotaran-extras/issues>.
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+pyglotaran_extras could always use more documentation, whether as part of the
+official pyglotaran_extras docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at <https://github.com/glotaran/pyglotaran-extras/issues>.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `pyglotaran_extras` for local development.
+
+1. Fork the `pyglotaran-extras` repo on GitHub.
+
+2. Clone your fork locally:
+
+   ```
+   $ git clone git@github.com:your_name_here/pyglotaran_extras.git
+   ```
+
+3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
+
+   ```
+   $ mkvirtualenv pyglotaran_extras
+   $ cd pyglotaran-extras/
+   $ pip install -e .
+   ```
+
+4. install the `pre-commit` and `pre-push` hooks:
+
+   ```
+   $ pre-commit install && pre-commit install -t pre-push
+   ```
+
+5. Create a branch for local development:
+
+   ```
+   $ git checkout -b name-of-your-bugfix-or-feature
+   ```
+
+   Now you can make your changes locally.
+
+6. When you're done making changes, check that your changes pass flake8 and the
+   tests, including testing other Python versions with tox:
+
+   ```
+   $ tox
+   ```
+
+   To get flake8 and tox, just pip install them into your virtualenv.
+
+7. Commit your changes and push your branch to GitHub:
+
+   ```
+   $ git add .
+   $ git commit -m "Your detailed description of your changes."
+   $ git push origin name-of-your-bugfix-or-feature
+   ```
+
+8. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.md.
+3. The pull request should work for Python 3.10 and 3.11. Check
+   <https://github.com/glotaran/pyglotaran-extras/actions>
+   and make sure that the tests pass for all supported Python versions.
+
+## Tips
+
+To run a subset of tests:
+
+```
+$ pytest tests.test_pyglotaran_extras
+```