docs: link to correct version on Binder/Colab

docs/conf.py

@@ -6,6 +6,7 @@
 """
 
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -15,14 +16,21 @@
 
 # -- Project information -----------------------------------------------------
 project = "TensorWaves"
-package = "tensorwaves"
-repo_name = "tensorwaves"
+PACKAGE = "tensorwaves"
+REPO_NAME = "tensorwaves"
 copyright = "2020, ComPWA"  # noqa: A001
 author = "Common Partial Wave Analysis"
 
-if os.path.exists(f"../src/{package}/version.py"):
-    __release = get_distribution(package).version
-    version = ".".join(__release.split(".")[:3])
+# https://docs.readthedocs.io/en/stable/builds.html
+BRANCH = os.environ.get("READTHEDOCS_VERSION", default="stable")
+if BRANCH == "latest":
+    BRANCH = "main"
+if re.match(r"^\d+$", BRANCH):  # PR preview
+    BRANCH = "stable"
+
+if os.path.exists(f"../src/{PACKAGE}/version.py"):
+    __RELEASE = get_distribution(PACKAGE).version
+    version = ".".join(__RELEASE.split(".")[:3])
 
 
 # -- Fetch logo --------------------------------------------------------------
@@ -34,16 +42,16 @@ def fetch_logo(url: str, output_path: str) -> None:
         stream.write(online_content.content)
 
 
-logo_path = "_static/logo.svg"
+LOGO_PATH = "_static/logo.svg"
 try:
     fetch_logo(
         url="https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg",
-        output_path=logo_path,
+        output_path=LOGO_PATH,
     )
 except requests.exceptions.ConnectionError:
     pass
-if os.path.exists(logo_path):
-    html_logo = logo_path
+if os.path.exists(LOGO_PATH):
+    html_logo = LOGO_PATH
 
 # -- Generate API ------------------------------------------------------------
 sys.path.insert(0, os.path.abspath("."))
@@ -55,7 +63,8 @@ def fetch_logo(url: str, output_path: str) -> None:
     " ".join(
         [
             "sphinx-apidoc",
-            f"../src/{package}/",
+            f"../src/{PACKAGE}/",
+            f"../src/{PACKAGE}/version.py",
             "-o api/",
             "--force",
             "--no-toc",
@@ -81,7 +90,7 @@ def fetch_logo(url: str, output_path: str) -> None:
 # The master toctree document.
 master_doc = "index"
 modindex_common_prefix = [
-    f"{package}.",
+    f"{PACKAGE}.",
 ]
 
 extensions = [
@@ -118,11 +127,11 @@ def fetch_logo(url: str, output_path: str) -> None:
         ]
     ),
 }
-autodoc_insert_signature_linebreaks = False
+AUTODOC_INSERT_SIGNATURE_LINEBREAKS = False
 graphviz_output_format = "svg"
 html_copy_source = True  # needed for download notebook button
 html_css_files = []
-if autodoc_insert_signature_linebreaks:
+if AUTODOC_INSERT_SIGNATURE_LINEBREAKS:
     html_css_files.append("linebreaks-api.css")
 html_favicon = "_static/favicon.ico"
 html_show_copyright = False
@@ -132,8 +141,8 @@ def fetch_logo(url: str, output_path: str) -> None:
 html_static_path = ["_static"]
 html_theme = "sphinx_book_theme"
 html_theme_options = {
-    "repository_url": f"https://github.com/ComPWA/{repo_name}",
-    "repository_branch": "stable",
+    "repository_url": f"https://github.com/ComPWA/{REPO_NAME}",
+    "repository_branch": BRANCH,
     "path_to_docs": "docs",
     "use_download_button": True,
     "use_edit_page_button": True,
@@ -164,45 +173,75 @@ def fetch_logo(url: str, output_path: str) -> None:
     ("py:obj", "Loss"),
 ]
 
+
 # Intersphinx settings
-PYTHON_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}"
-CONSTRAINTS_PATH = f"../.constraints/py{PYTHON_VERSION}.txt"
-with open(CONSTRAINTS_PATH) as stream:
-    CONSTRAINTS = stream.read()
-RELEASES = {}
-for line in CONSTRAINTS.split("\n"):
-    line = line.split("#")[0]  # remove comments
-    line = line.strip()
-    if not line:
-        continue
-    package, version = tuple(line.split("=="))
-    package = package.strip()
-    version = version.strip()
-    RELEASES[package] = version
+def get_version(package_name: str) -> str:
+    python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    constraints_path = f"../.constraints/py{python_version}.txt"
+    with open(constraints_path) as stream:
+        constraints = stream.read()
+    for line in constraints.split("\n"):
+        line = line.split("#")[0]  # remove comments
+        line = line.strip()
+        if not line.startswith(package_name):
+            continue
+        if not line:
+            continue
+        line_segments = line.split("==")
+        if len(line_segments) != 2:
+            continue
+        installed_version = line_segments[1]
+        installed_version = installed_version.strip()
+        return installed_version
+    return "stable"
+
+
+def get_minor_version(package_name: str) -> str:
+    installed_version = get_version(package_name)
+    if installed_version == "stable":
+        return installed_version
+    matches = re.match(r"^([0-9]+\.[0-9]+).*$", installed_version)
+    if matches is None:
+        raise ValueError(
+            f"Could not find documentation for {package_name} v{installed_version}"
+        )
+    return matches[1]
+
+
+__TF_URL = f"https://www.tensorflow.org/versions/r{get_minor_version('tensorflow')}/api_docs/python"
+r = requests.get(__TF_URL + "/tf")
+if r.status_code == 404:
+    __TF_URL = "https://www.tensorflow.org/api_docs/python"
 
 intersphinx_mapping = {
     "ampform": (
-        f"https://ampform.readthedocs.io/en/{RELEASES['ampform']}",
+        f"https://ampform.readthedocs.io/en/{get_version('ampform')}",
         None,
     ),
     "compwa-org": ("https://compwa-org.readthedocs.io/en/stable", None),
     "iminuit": ("https://iminuit.readthedocs.io/en/stable", None),
     "jax": ("https://jax.readthedocs.io/en/stable", None),
-    "matplotlib": ("https://matplotlib.org", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    "matplotlib": (
+        f"https://matplotlib.org/{get_version('matplotlib')}",
+        None,
+    ),
+    "numpy": (f"https://numpy.org/doc/{get_minor_version('numpy')}", None),
+    "pandas": (
+        f"https://pandas.pydata.org/pandas-docs/version/{get_version('pandas')}",
+        None,
+    ),
     "pwa": ("https://pwa.readthedocs.io", None),
     "python": ("https://docs.python.org/3", None),
     "qrules": (
-        f"https://qrules.readthedocs.io/en/{RELEASES['qrules']}",
+        f"https://qrules.readthedocs.io/en/{get_version('qrules')}",
         None,
     ),
-    "scipy": ("https://docs.scipy.org/doc/scipy", None),
-    "sympy": ("https://docs.sympy.org/latest", None),
-    "tensorflow": (
-        "https://www.tensorflow.org/api_docs/python",
-        "tensorflow.inv",
+    "scipy": (
+        f"https://docs.scipy.org/doc/scipy-{get_version('scipy')}",
+        None,
     ),
+    "sympy": ("https://docs.sympy.org/latest", None),
+    "tensorflow": (__TF_URL, "tensorflow.inv"),
 }
 
 # Settings for autosectionlabel
@@ -244,7 +283,19 @@ def fetch_logo(url: str, output_path: str) -> None:
     "colon_fence",
     "dollarmath",
     "smartquotes",
+    "substitution",
 ]
+BINDER_LINK = f"https://mybinder.org/v2/gh/ComPWA/{REPO_NAME}/{BRANCH}?filepath=docs/usage"
+myst_substitutions = {
+    "branch": BRANCH,
+    "run_interactive": f"""
+```{{margin}}
+Run this notebook [on Binder]({BINDER_LINK}) or
+{{ref}}`locally on Jupyter Lab <compwa-org:develop:Jupyter Notebooks>` to
+interactively modify the parameters.
+```
+""",
+}
 myst_update_mathjax = False
 
 # Settings for Thebe cell output

docs/index.md

@@ -6,10 +6,14 @@
 
 ```
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 [![10.5281/zenodo.5526650](https://zenodo.org/badge/doi/10.5281/zenodo.5526650.svg)](https://doi.org/10.5281/zenodo.5526650)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/tensorwaves)](https://pypi.org/project/tensorwaves)
-[![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComPWA/tensorwaves/blob/stable)
-[![Binder](https://static.mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ComPWA/tensorwaves/stable?filepath=docs/usage)
+{{ '[![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComPWA/tensorwaves/blob/{})'.format(branch) }}
+{{ '[![Binder](https://static.mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ComPWA/tensorwaves/{}?filepath=docs/usage)'.format(branch) }}
+<!-- markdownlint-enable -->
+<!-- prettier-ignore-end -->
 
 :::{margin}
 

docs/tensorflow.txt

@@ -3,8 +3,9 @@
 # Version: 2
 # The remainder of this file is compressed using zlib.
 
-tf.Tensor   py:class 1 tf/Tensor -
-tf.Variable py:class 1 tf/Variable -
-tensorflow.python.keras.losses.Loss py:class 1 tf/keras/losses/Loss -
-tensorflow.python.ops.stateful_random_ops.Generator py:class 1 tf/random/Generator -
-tensorflow.python.ops.variables.Variable py:class 1 tf/Variable -
+tensorflow.python.keras.losses.Loss                  py:class 1 tf/keras/losses/Loss -
+tensorflow.python.ops.stateful_random_ops.Generator  py:class 1 tf/random/Generator -
+tensorflow.python.ops.variables.Variable             py:class 1 tf/Variable -
+tf.Tensor                                            py:class 1 tf/Tensor -
+tf.Variable                                          py:class 1 tf/Variable -
+tf.summary                                           py:class 1 tf/summary -

src/tensorwaves/model.py

@@ -269,12 +269,13 @@ def tensorflow_lambdify() -> Callable:
 
 
 class LambdifiedFunction(Function):
+    """Implements `.Function` based on a `.Model` using {meth}`~.Model.lambdify`."""
+
     def __init__(
         self,
         model: Model,
         backend: Union[str, tuple, dict] = "numpy",
     ) -> None:
-        """Implements `.Function` based on a `.Model` using `~Model.lambdify`."""
         self.__lambdified_model = model.lambdify(backend=backend)
         self.__parameters = model.parameters
         self.__ordered_args = model.argument_order

src/tensorwaves/optimizer/callbacks.py

@@ -89,13 +89,14 @@ def on_function_call_end(
 
 
 class CSVSummary(Callback, Loadable):
+    """Log fit parameters and the estimator value to a CSV file."""
+
     def __init__(
         self,
         filename: str,
         function_call_step_size: int = 1,
         iteration_step_size: Optional[int] = None,
     ) -> None:
-        """Log fit parameters and the estimator value to a CSV file."""
         if iteration_step_size is None:
             iteration_step_size = 0
         if function_call_step_size <= 0 and iteration_step_size <= 0:
@@ -212,21 +213,22 @@ def cast_non_numeric(value: str) -> Union[complex, float, str]:
 
 
 class TFSummary(Callback):
+    """Log fit parameters and the estimator value to a `tf.summary`.
+
+    The logs can be viewed with `TensorBoard
+    <https://www.tensorflow.org/tensorboard>`_ via:
+
+    .. code-block:: shell
+
+        tensorboard --logdir logs
+    """
+
     def __init__(
         self,
         logdir: str = "logs",
         step_size: int = 10,
         subdir: Optional[str] = None,
     ) -> None:
-        """Log fit parameters and the estimator value to a `tf.summary`.
-
-        The logs can be viewed with `TensorBoard
-        <https://www.tensorflow.org/tensorboard>`_ via:
-
-        .. code-block:: shell
-
-            tensorboard --logdir logs
-        """
         self.__logdir = logdir
         self.__subdir = subdir
         self.__step_size = step_size
@@ -269,16 +271,17 @@ def on_function_call_end(
 
 
 class YAMLSummary(Callback, Loadable):
-    def __init__(self, filename: str, step_size: int = 10) -> None:
-        """Log fit parameters and the estimator value to a `tf.summary`.
+    """Log fit parameters and the estimator value to a `tf.summary`.
 
-        The logs can be viewed with `TensorBoard
-        <https://www.tensorflow.org/tensorboard>`_ via:
+    The logs can be viewed with `TensorBoard
+    <https://www.tensorflow.org/tensorboard>`_ via:
 
-        .. code-block:: shell
+    .. code-block:: shell
 
-            tensorboard --logdir logs
-        """
+        tensorboard --logdir logs
+    """
+
+    def __init__(self, filename: str, step_size: int = 10) -> None:
         self.__step_size = step_size
         self.__filename = filename
         self.__stream: IO = open(os.devnull, "w")

tox.ini

@@ -34,6 +34,8 @@ description =
 changedir = docs
 allowlist_externals =
     make
+passenv =
+    READTHEDOCS_VERSION
 commands =
     make html
 
@@ -44,6 +46,7 @@ allowlist_externals =
     sphinx-autobuild
 passenv =
     EXECUTE_NB
+    READTHEDOCS_VERSION
     TERM
 commands =
     sphinx-autobuild \
@@ -69,6 +72,8 @@ commands =
 [testenv:docnb]
 description =
     Build documentation through Sphinx WITH output of Jupyter notebooks
+passenv =
+    READTHEDOCS_VERSION
 setenv =
     EXECUTE_NB = "yes"
 changedir = docs
@@ -117,7 +122,5 @@ description =
     Run all notebooks with pytest
 allowlist_externals =
     pytest
-passenv =
-    EXECUTE_NB
 commands =
     pytest {posargs:docs} --nb-test-files