Dev (#3)

* docs: updates the docs

adds a starting version to the changelog, links to my PhD thesis in the overview, some info on create a release, and two more examples to the user guide

* chore: includes Python Semantic Release

adds python-semantic-release to dev deps, configures it in pyproject.toml, and adds a GA workflow in release.yml

* chore: updates docs

adds docs and changelog urls to project urls, ignores print warnings for ipynb's  for ruff

* chore: updates build and publish github actions

replaces build and twin with hynek build and inspect

* style: fixes style issues

* chore: removes release github action

comments out the release action to check where issues are occuring

.github/workflows/release.yml

@@ -10,36 +10,18 @@ on:
     types:
       - published
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-env:
-  FORCE_COLOR: 3
-
 jobs:
   dist:
-    name: Distribution build
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Build sdist and wheel
-        run: pipx run build
-
-      - uses: actions/upload-artifact@v3
-        with:
-          path: dist
-
-      - name: Check products
-        run: pipx run twine check dist/*
+      - uses: hynek/build-and-inspect-python-package@v1
 
   publish:
     needs: [dist]
-    name: Publish to PyPI
     environment: pypi
     permissions:
       id-token: write
@@ -53,8 +35,20 @@ jobs:
           path: dist
 
       - uses: pypa/gh-action-pypi-publish@release/v1
-        if: github.event_name == 'release' && github.event.action == 'published'
-        with:
-          # Remember to tell (test-)pypi about this repo before publishing
-          # Remove this line to publish to PyPI
-          repository-url: https://test.pypi.org/legacy/
+
+  # release:
+  #   runs-on: ubuntu-latest
+  #   concurrency: release
+  #   permissions:
+  #     id-token: write
+  #     contents: write
+
+  #   steps:
+  #     - uses: actions/checkout@v3
+  #       with:
+  #         fetch-depth: 0
+
+  #     - name: Python Semantic Release
+  #       uses: python-semantic-release/python-semantic-release@master
+  #       with:
+  #         github_token: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Version 0.1.0
+
+First release!

RELEASE.md

@@ -0,0 +1,30 @@
+# Release process for `invert4geom`
+
+We use _semantic versioning_, where version numbers are classified as
+v<major>.<minor>.<patch>. By default, releases are made from the main branch as
+part of a linear release history and, as described below, are triggered by
+pushing a git tag to the invert4geom repository on github. If a patch release is
+required for an older version, a branch can be created from the appropriate
+point in main and the following instructions are still apt.
+
+## Update the release notes:
+
+1. Make a list of merges, contributors, and reviewers::
+
+   ### Set release variables:
+
+   export VERSION=<about-to-be-released version number> export
+   PREVIOUS=<previous version number>
+
+   ### Autogenerate release notes
+
+   changelist mdtanker/invert4geom v${PREVIOUS} main --version ${VERSION}
+   --config pyproject.toml --out ${VERSION}.md
+
+   ### Put the output of the above command at the top of `CHANGELOG.md`
+
+   cat ${VERSION}.md | cat - CHANGELOG.md > temp && mv temp CHANGELOG.md
+
+2. Scan the PR titles for highlights and mention these in the relevant sections
+   of the notes. Ideally, all changed API objects are mentioned by name, e.g. a
+   new parameter or a deprecated function.

docs/changelog.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

docs/index.md

@@ -14,6 +14,8 @@ gallery/index
 :hidden:
 :caption: User guide
 user_guide/simple_inversion
+user_guide/including_starting_model
+user_guide/adhering_to_constraints
 ```
 
 ```{toctree}
@@ -22,6 +24,7 @@ user_guide/simple_inversion
 :caption: Reference documentation
 api/invert4geom
 citing.md
+changelog.md
 ```
 
 ```{toctree}

docs/overview.md

@@ -23,3 +23,11 @@ easily mapped.
 Currently, this package is only intended to perform inversions using right
 rectangular prisms. Other types of volumes, such as tesseroids, are currently
 not implemented.
+
+Much of this software was developed as part of my Ph.D. thesis. For detailed
+description of the theory and implementation of this inversion, as well as many
+synthetic tests and a real-world application to modelling bathymetry, see
+chapter 3 and 4 of my thesis, available
+[here](https://doi.org/10.26686/wgtn.24408304). The code was originally included
+in [this GitHub repository](https://github.com/mdtanker/RIS_gravity_inversion),
+but much of it has been migrated here.

pyproject.toml

@@ -69,6 +69,7 @@ dev = [
   "nox",
   "pre-commit",
   "pylint",
+  "python-semantic-release",
 ]
 docs = [
   "sphinx>=4.0",
@@ -82,9 +83,10 @@ docs = [
 
 [project.urls]
 Homepage = "https://github.com/mdtanker/invert4geom"
+Documentation = "https://invert4geom.readthedocs.io/"
 "Bug Tracker" = "https://github.com/mdtanker/invert4geom/issues"
 Discussions = "https://github.com/mdtanker/invert4geom/discussions"
-Changelog = "https://github.com/mdtanker/invert4geom/releases"
+Changelog = "https://invert4geom.readthedocs.io/en/latest/changelog.html"
 
 [tool.setuptools_scm]
 write_to = "src/invert4geom/_version.py"
@@ -191,7 +193,7 @@ extend-include = ["*.ipynb"]
 [tool.ruff.per-file-ignores]
 "tests/**" = ["T20"]
 "noxfile.py" = ["T20"]
-"*.ipynb" = ["E402", "B018"]
+"*.ipynb" = ["E402", "B018", "T201"]
 
 
 [tool.pylint]
@@ -206,3 +208,7 @@ messages_control.disable = [
   "missing-module-docstring",
   "wrong-import-position",
 ]
+
+[tool.semantic_release]
+version_variable = "pyproject.toml:version"
+major_on_zero = false