Merge pull request #238 from MPoL-dev/prev-docs

Add new wording about live documentation version and how to build docs for tagged versions if required.

docs/changelog.md

@@ -4,7 +4,8 @@
 
 ## v0.2.1
 
-- Changed API of {class}`~mpol.fourier.NuFFT`. Previous signature took `uu` and `vv` points at initialization (`__init__`), and the `.forward` method took only an image cube. This behaviour is preserved in a new class {class}`~mpol.fourier.NuFFTCached`. The updated signature of {class}`~mpol.fourier.NuFFT` *does not* take `uu` and `vv` at initialization. Rather, its `forward` method is modified to take an image cube and the `uu` and `vv` points. This allows an instance of this class to be used with new `uu` and `vv` points in each forward call. This follows the standard expectation of a layer (e.g., a linear regression function predicting at new `x`) and the pattern of the TorchKbNuFFT package itself. It is expected that the new `NuFFT` will be the default routine and `NuFFTCached` will only be used in specialized circumstances (and possibly deprecated/removed in future updates). Changes implemented by #232.
+- Changed API of {class}`~mpol.fourier.NuFFT`. Previous signature took `uu` and `vv` points at initialization (`__init__`), and the `.forward` method took only an image cube. This behaviour is preserved in a new class {class}`~mpol.fourier.NuFFTCached`. The updated signature of {class}`~mpol.fourier.NuFFT` *does not* take `uu` and `vv` at initialization. Rather, its `forward` method is modified to take an image cube and the `uu` and `vv` points. This allows an instance of this class to be used with new `uu` and `vv` points in each forward call. This follows the standard expectation of a layer (e.g., a linear regression function predicting at new `x`) and the pattern of the TorchKbNuFFT package itself. It is expected that the new `NuFFT` will be the default routine and `NuFFTCached` will only be used in specialized circumstances (and possibly deprecated/removed in future updates). Changes implemented by [#232](https://github.com/MPoL-dev/MPoL/pull/232).
+- Moved "Releasing a new version of MPoL" from the wiki to the Developer Documentation ({ref}`releasing-new-version-label`).
 
 ## v0.2.0
 

docs/developer-documentation.md

@@ -10,6 +10,8 @@ If you are new to contributing to an open source project, we recommend a quick r
 
 The MPoL project values stable software, and so we place a special emphasis on writing and running tests to ensure the code works reliably for as many users as possible. It is our intent that the `main` branch of the github repository always reflects a stable version of the code that passes all tests. After significant new functionality has been introduced, a tagged release (e.g., `v0.1.1`) is generated from the main branch and pushed to PyPI.
 
+See further below ({ref}`releasing-new-version-label`) for information on how to tag a new version using the GitHub and Zenodo workflows.
+
 ## Setting up your development environment
 
 ### Forking MPoL and cloning from Github
@@ -111,19 +113,26 @@ And then use your favorite web browser to open `htmlcov/index.html` and view the
 
 For more information on code coverage, see the [coverage.py documentation](https://coverage.readthedocs.io/en/coverage-5.5/). A worthy goal is to reach 100% code coverage with the testing suite. However, 100% coverage *doesn't mean the code is free of bugs*. More important than complete coverage is writing tests that properly probe program functionality.
 
+(documentation-build-reference-label)=
 ## Documentation
 
 MPoL documentation is written as docstrings attached to MPoL classes and functions and as individual `.rst` or `.md` files located in the `docs/` folder. The documentation is built using the [Sphinx](https://www.sphinx-doc.org/en/master/) Python documentation generator, with the [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html) plugin.
 
-### Dependencies
+### Versions and Dependencies
+
+After you've cloned the repository and changed to its root, you can optionally switch to a different package version or branch if needed. E.g., do 
 
-If you are only interested in building the documentation, you can install the more limited set of documentation package dependencies via
+```
+git fetch --tags
+git checkout tags/v0.2.0
+```
 
+Otherwise, proceed directly with installing the build dependencies for the documentation with 
 ```
 $ pip install ".[docs]"
 ```
 
-after you've cloned the repository and changed to the root of the repository. Otherwise, we recommend following the development environment instructions above, since the `[dev]` list is a superset of the `[docs]` list.
+Alternatively, you could start from `[dev]` list, since it is a superset of `[docs]`.
 
 ### Building the Documentation
 
@@ -217,3 +226,24 @@ When done, add a reference to your tutorial in the documentation table of conten
 Tutorials should be self-contained. If the tutorial requires a dataset, the dataset should be publicly available and downloaded at the beginning of the script. If the dataset requires significant preprocessing (e.g., some multi-configuration ALMA datasets), those preprocessing steps should be in the tutorial. If the steps are tedious, one solution is to upload a preprocessed dataset to Zenodo and have the tutorial download the data product from there (the preprocessing scripts/steps should still be documented in the Zenodo repo and/or as part of the [mpoldatasets repository](https://github.com/MPoL-dev/mpoldatasets)). The guiding principle is that other developers should be able to successfully build the tutorial from start to finish without relying on any locally provided resources or datasets.
 
 If you're thinking about contributing a tutorial and would like guidance on form or scope, please raise an [issue](https://github.com/MPoL-dev/MPoL/issues) or [discussion](https://github.com/MPoL-dev/MPoL/discussions) on the github repository.
+
+
+(releasing-new-version-label)=
+## Releasing a new version of MPoL
+
+To release a new version of MPoL, follow these steps in order:
+
+1. Ensure all tests are passing on your PR
+    * If tests are passing locally and failing in the GitHub Actions workflows, compare the code dependencies in `setup.py` with your local versions
+2. Ensure the docs build locally without errors or warnings
+3. Update the code version in `__init__`
+4. Update the version history in `changelog.md`
+5. Update the contributors in `CONTRIBUTORS.md`
+6. Update the copyright year and citation in `README.md`
+    * In the citation, update all fields except 'Zenodo', 'doi', and 'url' (the current DOI will cite all versions and the URL will direct to the most recent version)
+7. Merge your PR into `main`
+    * Ensure all tests triggered by the merge pass
+8. Publish a pre-release
+    * Ensure the `pre-release.yml` workflow passes
+9. Publish a (true) release, which will be automatically uploaded to PyPI and archived on Zenodo
+    * Verify this by ensuring the `package.yml` workflow passes

docs/index.rst

@@ -41,6 +41,11 @@ If you'd like to help build the MPoL package, please check out the :ref:`develop
    developer-documentation.md
    api.rst
 
+.. toctree::
+   :hidden:
+
+   changelog.md
+
 .. toctree::
    :maxdepth: 2
    :caption: Tutorials
@@ -57,10 +62,5 @@ If you'd like to help build the MPoL package, please check out the :ref:`develop
    ci-tutorials/fakedata
    large-tutorials/pyro
 
-.. toctree::
-   :hidden:
-
-   changelog.md
-
 * :ref:`genindex`
 * :ref:`changelog-reference-label`

docs/installation.md

@@ -4,12 +4,20 @@ MPoL requires `python >= 3.8`.
 
 ## Using pip
 
-Stable versions are hosted on PyPI and are installed via
+Stable versions are hosted on PyPI. You can install the latest version by
 
 ```
 $ pip install MPoL
 ```
 
+Or if you require a specific version of MPoL (e.g., `0.2.0`), you can install via
+
+```
+$ pip install MPoL==0.2.0
+```
+
+We recommend that you install the latest version of MPoL. Though, if you are working on a project across several compute environments, you may wish to ensure that each environment has the same version of MPoL installed.
+
 ## From source
 
 If you'd like to install the package from source to access the latest development version, download or `git clone` the MPoL repository and install
@@ -48,6 +56,12 @@ $ python
 >>> print(mpol.__version__)
 ```
 
+## Documentation
+
+The documentation served online ([here](https://mpol-dev.github.io/MPoL/index.html)) corresponds to the `main` branch. This represents the current state of MPoL and is usually the best place to reference MPoL functionality. However, this documentation may be more current than last tagged version or the version you have installed. If you require the new features detailed in the documentation, then we recommend installing the package from source (as above).
+
+In the (foreseeably rare) situation where the latest online documentation significantly diverges from the package version you wish to use (but there are reasons you do not want to build the `main` branch from source), you can access the documentation for that version by {ref}`building and viewing the documentation locally <documentation-build-reference-label>`. To do so, clone the repository as above, checkout the version tag, and build the docs locally.
+
 ## Using CUDA acceleration
 
 MPoL uses PyTorch for its Neural Networks as seen in the `Optimization Loop` tutorial. If you are interested in using PyTorch's full potential by utilizing a Nvidia graphics card, then the CUDA tool kit will need to be installed (TensorVision is also required). More information on this is available in the `GPU Tutorial` page. It is worth noting that PyTorch may need to be (re)installed separately using a specific `pip` for your system.

src/mpol/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 zenodo_record = 10064221