docs: link to correct version on Binder/Colab (#339)

* docs: pin more intersphinx pages * fix: correct intersphinx links that were not previously checked * fix: exclude version 'module' from API * fix: move docstrings from __init__ to class definition * refactor: get intersphinx version through function * style: capitalize conf.py global vars that are no Sphinx options
ComPWA · Nov 5, 2021 · a1491f5 · a1491f5
1 parent ad6d775
commit a1491f5
Show file tree

Hide file tree

Showing 9 changed files with 134 additions and 71 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -50,6 +50,7 @@
     ],
     "language": "en-US",
     "words": [
+        "ComPWA",
         "backends",
         "blatt",
         "bottomness",

diff --git a/docs/conf.py b/docs/conf.py
@@ -8,22 +8,31 @@
 """
 
 import os
+import re
 import shutil
 import subprocess
 import sys
 
+import requests
 from pkg_resources import get_distribution
 
 # -- Project information -----------------------------------------------------
 project = "TensorWaves"
-package = "tensorwaves"
-repo_name = "tensorwaves"
-copyright = "2020, ComPWA"
+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])
 
 # -- Generate API ------------------------------------------------------------
 sys.path.insert(0, os.path.abspath("."))
@@ -34,7 +43,8 @@
     " ".join(
         [
             "sphinx-apidoc",
-            f"../src/{package}/",
+            f"../src/{PACKAGE}/",
+            f"../src/{PACKAGE}/version.py",
             "-o api/",
             "--force",
             "--no-toc",
@@ -60,7 +70,7 @@
 # The master toctree document.
 master_doc = "index"
 modindex_common_prefix = [
-    f"{package}.",
+    f"{PACKAGE}.",
 ]
 
 extensions = [
@@ -97,11 +107,11 @@
         ]
     ),
 }
-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
@@ -111,8 +121,8 @@
 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,
@@ -143,43 +153,70 @@
 ]
 
 # 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 = dict()
-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),
+    "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/reference/", 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')}/reference",
+        None,
     ),
+    "sympy": ("https://docs.sympy.org/latest", None),
+    "tensorflow": (__TF_URL, "tensorflow.inv"),
 }
 
 # Settings for autosectionlabel
@@ -221,7 +258,19 @@
     "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

diff --git a/docs/index.md b/docs/index.md
@@ -6,10 +6,14 @@
 
 ```
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 [![PyPI package](https://badge.fury.io/py/tensorwaves.svg)](https://pypi.org/project/tensorwaves)
 [![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}
 

diff --git a/docs/install.md b/docs/install.md
@@ -20,8 +20,8 @@ python3 -m pip install git+https://github.com/ComPWA/tensorwaves@main
 ```
 
 In that case, however, we highly recommend using the more dynamic
-{ref}`'editable installation' <pwa:develop:Editable installation>` instead.
-This goes as follows:
+{ref}`'editable installation' <compwa-org:develop:Editable installation>`
+instead. This goes as follows:
 
 :::{margin}
 
@@ -41,11 +41,12 @@ This goes as follows:
    ```
 
 2. **[Recommended]** Create a virtual environment (see
-   {ref}`here <pwa:develop:Virtual environment>`).
+   {ref}`here <compwa-org:develop:Virtual environment>`).
 
 3. Install the project as an
-   {ref}`'editable installation' <pwa:develop:Editable installation>` and
-   install {ref}`additional packages <pwa:develop:Optional dependencies>` for
+   {ref}`'editable installation' <compwa-org:develop:Editable installation>`
+   and install
+   {ref}`additional packages <compwa-org:develop:Optional dependencies>` for
    the developer:
 
    ```shell
@@ -72,5 +73,5 @@ This goes as follows:
    :::
 
 That's all! Have a look at the {doc}`/usage` page to try out the package. You
-can also have a look at the {doc}`pwa:develop` page for tips on how to work
-with this 'editable' developer setup!
+can also have a look at the {doc}`compwa-org:develop` page for tips on how to
+work with this 'editable' developer setup!
diff --git a/docs/tensorflow.txt b/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 -
diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb
@@ -188,7 +188,7 @@
    "metadata": {},
    "source": [
     "```{margin}\n",
-    "We use {attr}`~sympy.core.basic.Basic.args` here to extract the components of the sum that forms this expression. See {doc}`sympy:tutorial/manipulation`.\n",
+    "We use `args` here to extract the components of the sum that forms this expression. See {doc}`sympy:tutorial/manipulation`.\n",
     "```"
    ]
   },

diff --git a/src/tensorwaves/model.py b/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
@@ -447,7 +448,7 @@ class SympyModel(Model):
 
     Args: expression : A sympy expression that contains the complete
         information of the model based on some inputs. The inputs are defined
-        via the `~sympy.core.basic.Basic.free_symbols` attribute of the
+        via the :code:`free_symbols` attribute of the
         `sympy.Expr <sympy.core.expr.Expr>`. parameters: Defines which inputs
         of the model are parameters. The keys represent the parameter set,
         while the values represent their default values. Consequently the

diff --git a/src/tensorwaves/optimizer/callbacks.py b/src/tensorwaves/optimizer/callbacks.py
@@ -87,13 +87,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:
@@ -210,21 +211,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
@@ -267,16 +269,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")