Updated and documented development environment.

demos/ReadMe.md

@@ -0,0 +1,4 @@
+## Demonstration scripts
+
+The scripts here demonstrate simple use cases and are referenced in
+the "Demonstration" chapter of the documentation.

docs/ReadMe.md

@@ -0,0 +1,6 @@
+## Documentation source files
+
+The documentation hosted on Read-the-Docs is built from this folder.
+As Read-the-Docs does not parse `pyproject.toml`, the requirement
+declaration for a documentation build is duplicated here in
+`requirements.txt`. The start page corresponds to `index.md`.

pyproject.toml

@@ -21,13 +21,23 @@ classifiers = [
     'Natural Language :: English',
     'License :: OSI Approved :: MIT License']
 readme = 'PyPI.md'
-requires-python = '>=3.6'
-dependencies = ['JPype1', 'NumPy']
 dynamic = ['version', 'description']
+requires-python = '>= 3.6'
+dependencies = [
+    'JPype1',
+    'NumPy',
+]
 
 [project.optional-dependencies]
-docs = ['Sphinx', 'Furo', 'MyST-parser']
-test = ['pyTest', 'pyTest-cov', 'Flake8', 'Flake8-pyproject']
+dev = [
+    'Sphinx',
+    'Furo',
+    'MyST-parser',
+    'pyTest',
+    'pyTest-cov',
+    'Flake8-pyproject',
+    'Flit',
+]
 
 [project.urls]
 Documentation = 'https://mph.readthedocs.io'
@@ -37,38 +47,41 @@ Source = 'https://github.com/MPh-py/MPh'
 # Wheel builder: Flit
 
 [build-system]
-requires = ['flit_core>=3.4,<4']
+requires = ['flit_core >= 3.4, < 4']
 build-backend = 'flit_core.buildapi'
 
 [tool.flit.module]
 name = 'mph'
 
 
-# Code linter: Flake8 (via pyproject-Flake8)
+# Code linter: Flake8
 
 [tool.flake8]
 exclude = [
-    '.git', '__pycache__',
-    'local', 'ignore', 'develop', 'dev',
+    'local',  '.local',
+    'ignore', '.ignore',
+    'venv',   '.venv',
 ]
 ignore = [
-    'E127',        # Continuation line over-indented for visual indent.
-    'E128',        # Continuation line under-indented for visual indent.
-    'E201',        # Whitespace after '('.
-    'E202',        # Whitespace before ')'.
-    'E221',        # Multiple spaces before operator.
-    'E222',        # Multiple spaces after operator.
-    'E226',        # Missing whitespace around arithmetic operator.
-    'E231',        # Missing whitespace after ',', ';', or ':'.
-    'E241',        # Multiple spaces after ','.
-    'E251',        # Unexpected spaces around keyword / parameter equals.
-    'E261',        # At least two spaces before inline comment.
-    'E271',        # Multiple spaces after keyword.
-    'E272',        # Multiple spaces before keyword.
-    'E402',        # Module level import not at top of file.
-    'W503',        # Line break occurred before a binary operator.
+    'E127',                  # Continuation line over-indented.
+    'E128',                  # Continuation line under-indented.
+    'E201',                  # Whitespace after '('.
+    'E202',                  # Whitespace before ')'.
+    'E221',                  # Multiple spaces before operator.
+    'E222',                  # Multiple spaces after operator.
+    'E226',                  # Missing whitespace around arithmetic operator.
+    'E231',                  # Missing whitespace after ',', ';', or ':'.
+    'E241',                  # Multiple spaces after ','.
+    'E251',                  # Unexpected spaces around keyword equals.
+    'E261',                  # At least two spaces before inline comment.
+    'E271',                  # Multiple spaces after keyword.
+    'E272',                  # Multiple spaces before keyword.
+    'E402',                  # Module level import not at top of file.
+    'W503',                  # Line break occurred before a binary operator.
+]
+per-file-ignores = [
+    '__init__.py:F401',      # Imported but unused.
 ]
-per-file-ignores = ['__init__.py:F401']
 
 
 # Test runner: pyTest
@@ -88,6 +101,5 @@ relative_files = true
 [tool.coverage.report]
 exclude_lines = [
     'pragma: no cover',
-    'def check_environment',
     'def location',
 ]

tests/ReadMe.md

@@ -0,0 +1,12 @@
+## Test suite
+
+The scripts here, along with some fixtures, constitute the test suite.
+They are run in the intended order by the helper scripts `test.py` and
+`coverage.py` in the `tools` folder.
+
+Note that when running those scripts from the project folder, i.e. the
+parent folder of this one here, then they will test what's inside the
+`mph` folder, i.e. the current source code. If run from anywhere else,
+they would test whatever `import mph` finds, which may be an installed
+version of MPh. This behavior is intentional, so that new code can be
+tested without touching the installed version.

tools/ReadMe.md

@@ -0,0 +1,61 @@
+## Automation tools for local development
+
+These are simple helper scripts to run the various dev tools, such as
+pyTest or Flit. See the doc-strings of the individual scripts for
+details.
+
+
+### Local development
+
+MPh can be used and tested from source, provided NumPy, JPype, and pyTest
+are already installed. That is, the following runs the test suite for what
+is currently in the `main` branch:
+```console
+git clone https://github.com/MPh-py/MPh.git
+cd MPh
+python tools/test.py
+```
+
+This works because when you are in the project folder (named `MPh`),
+then `import mph` will find the subfolder `mph` and run the code from
+there, possibly ignoring a different MPh version installed in the
+Python environment.
+
+If you also want to build the documentation locally, or render the
+code-coverage report, or build the wheel, it's best to create a dedicated
+virtual environment:
+```console
+python -m venv venv --upgrade-deps
+venv/Scripts/activate                  # Windows
+venv/bin/activate                      # Linux/macOS
+pip install --editable .[dev]
+```
+
+This installs MPh and all its development dependencies inside that
+new environment, in the newly created `venv` sub-folder. The `dev`
+dependencies are defined in `pyproject.toml`.
+
+
+### Releasing a new version
+
+* Bump version number in `mph/meta.py`.
+* Add release notes to `docs/releases.md`.
+* Add dedicated commit for the version bump.
+* Tag commit with version number, e.g. `git tag v1.1.7`.
+* Force `stable` branch to latest commit: `git branch -f stable`.
+* Same for the current documentation branch: `git branch -f 1.1`.
+* Run code linter: `flake8`.
+* Test docs build: `python tools/docs.py`.
+* Test wheel build: `python tools/wheel.py`.
+* Run tests for each supported Python/OS: `python3x tools/test.py`.
+* Run code coverage: `python tools/coverage.py`.
+* Push to GitHub:
+```console
+    git push origin main
+    git push --tags
+    git push origin stable
+    git push origin 1.1
+```
+* Upload coverage report: `python tools/codecov.py`.
+* Create new release on GitHub and add release notes.
+* Publish to PyPI: `python tools/publish.py`.