Build docs for stable branch and make default (#353)

oliverholworthy · web-flow · commit f307dc2ee784 · 2023-06-01T12:05:42.000-04:00
* Pin numpy to &lt;1.24 to ensure older Merlin API docs can be built

* Setup local branches for docs build

* Setup redirect to stable branch of docs

* Link to stable version of docs in README.md

* Only build docs for tags that match a release pattern

* Build docs for stable branch and set this as the core version

* Update comment in docs.txt

* Import re in conf.py

* Link to stable branch in notebooks

* Update canonical docs branch to stable
diff --git a/.github/workflows/docs-sched-rebuild.yaml b/.github/workflows/docs-sched-rebuild.yaml
@@ -26,6 +26,10 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools==59.4.0 wheel tox
+      - name: Setup local branches for docs build
+        run: |
+          git branch --track main origin/main || true
+          git branch --track stable origin/stable || true
       - name: Building docs (multiversion)
         run: |
           tox -e docs-multi
@@ -82,28 +86,28 @@ jobs:
             echo "The redirect file already exists."
             exit 0
           fi
-          # If any of these commands fail, fail the build.
-          def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch")
+          def_branch="stable"
           html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url")
-          # Beware ugly quotation mark avoidance in the foll lines.
-          echo '<!DOCTYPE html>'                                                                         > index.html
-          echo '<html>'                                                                                 >> index.html
-          echo '  <head>'                                                                               >> index.html
-          echo '    <title>Redirect to documentation</title>'                                           >> index.html
-          echo '    <meta charset="utf-8">'                                                             >> index.html
-          echo '    <meta http=equiv="refresh" content="3; URL='${html_url}${def_branch}'/index.html">' >> index.html
-          echo '    <link rel="canonical" href="'${html_url}${def_branch}'/index.html">'                >> index.html
-          echo '    <script language="javascript">'                                                     >> index.html
-          echo '      function redirect() {'                                                            >> index.html
-          echo '        window.location.assign("'${html_url}${def_branch}'/index.html")'                >> index.html
-          echo '      }'                                                                                >> index.html
-          echo '    </script>'                                                                          >> index.html
-          echo '  </head>'                                                                              >> index.html
-          echo '  <body onload="redirect()">'                                                           >> index.html
-          echo '    <p>Please follow the link to the <a href="'${html_url}${def_branch}'/index.html">'  >> index.html
-          echo      ${def_branch}'</a> branch documentation.</p>'                                       >> index.html
-          echo '  </body>'                                                                              >> index.html
-          echo '</html>'                                                                                >> index.html
+          cat > index.html << EOF
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>Redirect to documentation</title>
+              <meta charset="utf-8">
+              <meta http=equiv="refresh" content="3; URL="${html_url}${def_branch}/index.html"
+              <link rel="canonical" href="'${html_url}${def_branch}/index.html">
+              <script language="javascript">
+                function redirect() {
+                  window.location.assign("${html_url}${def_branch}/index.html")
+                }
+              </script>
+            </head>
+            <body onload="redirect()">
+              <p>Please follow the link to the <a href="${html_url}${def_branch}/index.html">
+              ${def_branch}'</a> branch documentation.</p>
+            </body>
+          </html>
+          EOF
           git add index.html
       - name: Commit changes to the GitHub Pages branch
         run: |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,7 +23,7 @@ into three categories:
 
 ### Your first issue
 
-1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/systems/blob/main/README.md)
+1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/systems/blob/stable/README.md)
    to learn how to setup the development environment.
 2. Find an issue to work on. The best way is to look for the [good first issue](https://github.com/NVIDIA-Merlin/systems/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
    or [help wanted](https://github.com/NVIDIA-Merlin/systems/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/merlin-systems)
 [![PyPI version shields.io](https://img.shields.io/pypi/v/merlin-systems.svg)](https://pypi.python.org/pypi/merlin-systems/)
 ![GitHub License](https://img.shields.io/github/license/NVIDIA-Merlin/systems)
-[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/systems/main/README.html)
+[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/systems/stable/README.html)
 
 Merlin Systems provides tools for combining recommendation models with other elements of production recommender systems like feature stores, nearest neighbor search, and exploration strategies into end-to-end recommendation pipelines that can be served with [Triton Inference Server](https://github.com/triton-inference-server/server).
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import re
 import subprocess
 import sys
 
@@ -96,12 +97,13 @@
 
 if os.path.exists(gitdir):
     tag_refs = subprocess.check_output(["git", "tag", "-l", "v*"]).decode("utf-8").split()
+    tag_refs = [tag for tag in tag_refs if re.match(r"^v[0-9]+.[0-9]+.[0-9]+$", tag)]
     tag_refs = natsorted(tag_refs)[-6:]
     smv_tag_whitelist = r"^(" + r"|".join(tag_refs) + r")$"
 else:
     smv_tag_whitelist = r"^v.*$"
 
-smv_branch_whitelist = r"^main$"
+smv_branch_whitelist = r"^(main|stable)$"
 
 smv_refs_override_suffix = r"-docs"
 
@@ -110,11 +112,11 @@
     "cudf": ("https://docs.rapids.ai/api/cudf/stable/", None),
     "distributed": ("https://distributed.dask.org/en/latest/", None),
     "torch": ("https://pytorch.org/docs/stable/", None),
-    "merlin-core": ("https://nvidia-merlin.github.io/core/main/", None),
+    "merlin-core": ("https://nvidia-merlin.github.io/core/stable/", None),
 }
 
 html_sidebars = {"**": ["versions.html"]}
-html_baseurl = "https://nvidia-merlin.github.io/systems/main"
+html_baseurl = "https://nvidia-merlin.github.io/systems/stable/"
 
 autodoc_inherit_docstrings = False
 autodoc_default_options = {
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -13,7 +13,7 @@ Merlin Systems GitHub Repository
 
 About Merlin
   Merlin is the overarching project that brings together the Merlin projects.
-  See the `documentation <https://nvidia-merlin.github.io/Merlin/main/README.html>`_
+  See the `documentation <https://nvidia-merlin.github.io/Merlin/stable/README.html>`_
   or the `repository <https://github.com/NVIDIA-Merlin/Merlin>`_ on GitHub.
 
 Developer website for Merlin
diff --git a/examples/Serving-An-Implicit-Model-With-Merlin-Systems.ipynb b/examples/Serving-An-Implicit-Model-With-Merlin-Systems.ipynb
@@ -80,7 +80,7 @@
    "source": [
     "In this tutorial our objective is to demonstrate how to serve an `Implicit` model. In order for us to be able to do so, we begin by downloading data and training a model. We breeze through these activities below.\n",
     "\n",
-    "If you would like to learn more about training an `Implicit` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/main/examples/07-Train-traditional-ML-models-using-the-Merlin-Models-API.ipynb)."
+    "If you would like to learn more about training an `Implicit` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/07-Train-traditional-ML-models-using-the-Merlin-Models-API.ipynb)."
    ]
   },
   {
diff --git a/examples/Serving-An-XGboost-Model-With-Merlin-Systems.ipynb b/examples/Serving-An-XGboost-Model-With-Merlin-Systems.ipynb
@@ -80,7 +80,7 @@
    "source": [
     "In this tutorial our objective is to demonstrate how to serve an `XGBoost` model. In order for us to be able to do so, we begin by downloading data and training a model. We breeze through these activities below.\n",
     "\n",
-    "If you would like to learn more about training an `XGBoost` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/main/examples/07-Train-an-xgboost-model-using-the-Merlin-Models-API.ipynb)."
+    "If you would like to learn more about training an `XGBoost` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/07-Train-an-xgboost-model-using-the-Merlin-Models-API.ipynb)."
    ]
   },
   {
diff --git a/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb b/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb
@@ -35,7 +35,7 @@
     "\n",
     "# Serving Ranking Models With Merlin Systems\n",
     "\n",
-    "This notebook is created using the latest stable [merlin-tensorflow](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow/tags) container. This Jupyter notebook example demonstrates how to deploy a ranking model to Triton Inference Server (TIS) and generate prediction results for a given query. As a prerequisite, the ranking model must be trained and saved with Merlin Models. Please read the [README](https://github.com/NVIDIA-Merlin/systems/blob/main/examples/README.md) for the instructions.\n",
+    "This notebook is created using the latest stable [merlin-tensorflow](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow/tags) container. This Jupyter notebook example demonstrates how to deploy a ranking model to Triton Inference Server (TIS) and generate prediction results for a given query. As a prerequisite, the ranking model must be trained and saved with Merlin Models. Please read the [README](https://github.com/NVIDIA-Merlin/systems/blob/stable/examples/README.md) for the instructions.\n",
     "\n",
     "## Overview\n",
     "\n",
@@ -57,7 +57,7 @@
     "\n",
     "### Dataset\n",
     "\n",
-    "We use the synthetic train and test datasets generated by mimicking the real [Ali-CCP: Alibaba Click and Conversion Prediction](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1) dataset to build our recommender system ranking models. To see how the data is transformed with NVTabular and how a DLRM model is trained with Merlin Models check out the [04-Exporting-ranking-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/main/examples/04-Exporting-ranking-models.ipynb) example notebook which is a prerequisite for this notebook.\n",
+    "We use the synthetic train and test datasets generated by mimicking the real [Ali-CCP: Alibaba Click and Conversion Prediction](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1) dataset to build our recommender system ranking models. To see how the data is transformed with NVTabular and how a DLRM model is trained with Merlin Models check out the [04-Exporting-ranking-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/04-Exporting-ranking-models.ipynb) example notebook which is a prerequisite for this notebook.\n",
     "\n",
     "It is important to note that the steps take in this notebook are generalized and can be applied to any set of workflow and models. \n",
     "\n",
@@ -96,7 +96,7 @@
    "source": [
     "## Load an NVTabular Workflow\n",
     "\n",
-    "First, we load the `nvtabular.Workflow` that we created in with this [example](https://github.com/NVIDIA-Merlin/models/blob/main/examples/04-Exporting-ranking-models.ipynb). "
+    "First, we load the `nvtabular.Workflow` that we created in with this [example](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/04-Exporting-ranking-models.ipynb). "
    ]
   },
   {
@@ -156,7 +156,7 @@
    "source": [
     "## Load the Tensorflow Model\n",
     "\n",
-    "After loading the workflow, we load the model. This model was trained with the output of the workflow from the [Exporting Ranking Models](https://github.com/NVIDIA-Merlin/models/blob/main/examples/04-Exporting-ranking-models.ipynb) example from Merlin Models."
+    "After loading the workflow, we load the model. This model was trained with the output of the workflow from the [Exporting Ranking Models](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/04-Exporting-ranking-models.ipynb) example from Merlin Models."
    ]
   },
   {
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -15,3 +15,8 @@ myst-nb==0.13.2
 linkify-it-py==1.0.3
 sphinx-external-toc==0.2.4
 attrs==21.4.0
+
+# keep support for numpy builtin type aliases for previous tags
+# numpy builtin aliases like np.str were removed in 1.24
+# This can be unpinned when we no longer build docs for versions of Merlin prior 23.05
+numpy<1.24

Original file line number	Diff line number	Diff line change
`@@ -80,7 +80,7 @@`
`80`	`80`	`"source": [`
`81`	`81`	"In this tutorial our objective is to demonstrate how to serve an `Implicit` model. In order for us to be able to do so, we begin by downloading data and training a model. We breeze through these activities below.\n",
`82`	`82`	`"\n",`
`83`		- "If you would like to learn more about training an `Implicit` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/main/examples/07-Train-traditional-ML-models-using-the-Merlin-Models-API.ipynb)."
	`83`	+ "If you would like to learn more about training an `Implicit` model using the Merlin Models library, please consult this [tutorial](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/07-Train-traditional-ML-models-using-the-Merlin-Models-API.ipynb)."
`84`	`84`	`]`
`85`	`85`	`},`
`86`	`86`	`{`