Fix ROOT version in docs (#1043)

We opt for a manual update strategy for the ROOT version, because it
changes slowly and an efficient way to do it automatically in CI is
elusive. Instructions were added to the release.md instructions and
conf.py in the doc folder.

#### What is the problem with doing it in CI?

Since the ROOT repo is huge, we want to make shallow clones for git
submodules, but then we cannot determine the relation of the commit to
the closest tag, because that history which connects tag and commit is
not there. Checking out all tags with `git pull --tags` takes a lot of
bandwidth, and is not enough. We also need to check out the history
between the latest tag and the commit. We don't know which tag the
commit is closest to, so the best way would be to iteratively load the
most recent history until the commit is connected to a tag.

doc/conf.py

@@ -1,12 +1,15 @@
 import os
-from iminuit import __version__ as version
-import sys
 
-sys.path.append(".")
+# release and version are special variables used by sphinx
+from iminuit import __version__ as version
 
-from root_version import root_version  # noqa
+# We set the root_version manually, because it setting it
+# automatically and efficiently in CI is difficult.
+# To update the number:
+# - Make sure you have a full clone, not a shallow clone of ROOT.
+# - Run `doc/root_version.py` and copy the string here.
+root_version = "v6-25-02-9213-g754d22635f"
 
-# release and version are special variables used by sphinx
 
 with open("../README.rst") as f:
     readme_content = f.read()
@@ -49,6 +52,7 @@
 nbsphinx_execute = "auto"
 # use FAST=1 to speed up doc build
 if bool(os.environ.get("FAST", False)):
+    print("Fast generation activated")
     nbsphinx_execute = "never"
 
 autoclass_content = "both"

doc/release.md

@@ -1,15 +1,20 @@
-How to make a release
-=====================
+# How to make a release
 
 - Sync local `main` and `develop` with Github
+
   - `for x in main develop; git checkout $x; git pull`
+
 - On `develop` branch
+
   - Update version in `pyproject.toml`
     - For a beta release, add `.betaN`, where N is a number >= 0
     - For a release candidate, add `.rcN`
   - Run `python3 doc/update_changelog.py` or update `doc/changelog.rst` manually
     - Check the output if you used the script
+  - If necessary, update ROOT version in `doc/conf.py`, see instructions there
+
 - Merge `develop` into `main`
+
   - Every push to `main` triggers building wheels, uploading to PyPI, and tagging/publishing on GitHub
   - If there are problems with the wheels, commit fixes to `develop`, then merge again into `main`
   - Note: Upload to PyPI uses API tokens configured in PyPI and Github "Secrets"

doc/root_version.py

@@ -25,4 +25,4 @@
     .decode()
     .strip()
 )
-print("ROOT", root_version)
+print(root_version)

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "scikit_build_core.build"
 [project]
 name = "iminuit"
 description = "Jupyter-friendly Python frontend for MINUIT2 in C++"
-version = "2.29.1"
+version = "2.30.0"
 maintainers = [{ name = "Hans Dembinski", email = "[email protected]" }]
 readme = "README.rst"
 requires-python = ">=3.9"