Merge pull request hyperspy#3321 from ericpre/documentation_release_w…

…orkflow

Documentation release workflow

.github/workflows/doc.yml

@@ -12,3 +12,33 @@ jobs:
       # graphviz is required to build mermaid graph
       # optipng is required to optimize thumbnail
       install_package_ubuntu: graphviz optipng
+
+  Push_dev:
+    needs: Build
+    # Push only on the "RELEASE_next_minor" and update the "dev" documentation
+    if: ${{ github.repository_owner == 'hyperspy' && github.ref_name == 'RELEASE_next_minor' }}
+    permissions:
+      # needs write permission to push the docs to gh-pages
+      contents: write
+    # Use the "reusable workflow" from the hyperspy organisation
+    uses: hyperspy/.github/.github/workflows/push_doc.yml@main
+    with:
+      repository: 'hyperspy/hyperspy-doc'
+      output_path: 'dev'
+    secrets:
+      access_token: ${{ secrets.PAT_DOCUMENTATION }}
+
+  Push_tag:
+    needs: Build
+    # Push only on tag and update the "current" documentation
+    if: ${{ github.repository_owner == 'hyperspy' && startsWith(github.ref, 'refs/tags/') }}
+    permissions:
+      # needs write permission to push the docs to gh-pages
+      contents: write
+    # Use the "reusable workflow" from the hyperspy organisation
+    uses: hyperspy/.github/.github/workflows/push_doc.yml@main
+    with:
+      repository: 'hyperspy/hyperspy-doc'
+      output_path: 'current'
+    secrets:
+      access_token: ${{ secrets.PAT_DOCUMENTATION }}

doc/dev_guide/writing_docs.rst

@@ -1,5 +1,4 @@
 
-
 .. _writing_documentation-label:
 
 Writing documentation
@@ -101,3 +100,22 @@ cross-references. For example, to find how to write a cross-reference to
   Name                                                      Score
   ---------------------------------------------------------  -------
   :meth:`hyperspy.signal.BaseSignal.set_signal_type`      90
+
+.. _versioned_documentation:
+
+Hosting versioned documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Builds of the documentation for each minor and major release are hosted in the https://github.com/hyperspy/hyperspy-doc
+repository and are used by the `version switcher <https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html>`_
+of the documentation.
+
+The ``"dev"`` version is updated automatically when pushing on the ``RELEASE_next_minor`` branch and the `"current"` (stable)
+version is updated automatically when a tag is pushed.
+When releasing a minor and major release, two manual steps are required:
+
+1. in https://github.com/hyperspy/hyperspy-doc, copy the "current" stable documentation to a separate folder named with the corresponding version 
+2. update the documentation version switch, in ``doc/_static/switcher.json``:
+
+   - copy and paste the `"current"`` documentation entry
+   - update the version in the "current" entry to match the version to be released, e.g. increment the minor or major digit
+   - in the newly created entry, update the link to the folder created in step 1.

hyperspy/drawing/utils.py

@@ -1829,8 +1829,8 @@ def plot_roi_map(signal, rois=1):
     The ROIs can be moved interactively and the corresponding plots will
     update automatically.
 
-    Arguments
-    ---------
+    Parameters
+    ----------
     signal: :class:`~.api.signals.BaseSignal`
         The signal to inspect.
     rois: int, list of :class:`~.api.roi.SpanROI` or :class:`~.api.roi.RectangularROI`

releasing_guide.md

@@ -9,6 +9,7 @@ Create a PR to the `RELEASE_next_patch` branch and go through the following step
   - update the release notes in `CHANGES.rst` by running `towncrier`,
   - update the `setuptools_scm` fallback version in `pyproject.toml`.
 - Check release notes
+- For a minor or major release, update the versioned documentation repository and documentation version switcher according to the instruction in the [developer guide](https://hyperspy.org/hyperspy-doc/current/dev_guide/writing_docs.html#hosting-versioned-documentation)
 - (optional) check conda-forge and wheels build. Pushing a tag to a fork will run the release workflow without uploading to pypi
 - Let that PR collect comments for a day to ensure that other maintainers are comfortable with releasing
 
@@ -23,6 +24,7 @@ Create a PR to the `RELEASE_next_patch` branch and go through the following step
 **Post-release action**
 - Merge the PR
 
+
 Follow-up
 =========
 

upcoming_changes/3321.maintenance.rst

@@ -0,0 +1 @@
+Add documentation on how the documentation is updated and the required manual changes for minor and major releases.