Add some example notebooks and a notebook related files sidebar item (#…

…108)

* Copy in a couple of notebooks from cloud-ml-examples for testing

* Add custom sphinx extension to show related files in notebook sidebar

.gitignore

@@ -1,2 +1,4 @@
 build
 *.swp
+
+__pycache__

conda/environments/deployment_docs.yml

@@ -7,7 +7,7 @@ dependencies:
   - myst-parser
   - nbsphinx
   - numpydoc
-  - pydata-sphinx-theme
+  - pydata-sphinx-theme>=0.12.0
   - python=3.9
   - pre-commit
   - sphinx

extensions/rapids_notebook_files.py

@@ -0,0 +1,40 @@
+import pathlib
+
+
+def find_notebook_related_files(app, pagename, templatename, context, doctree):
+    """Find related files for Jupyter Notebooks in the examples section.
+
+    Example notebooks should be placed in /source/examples in their own directories.
+    This extension walks through the directory when each notebook is rendered and generates
+    a list of all the other files in the directory.
+
+    The goal is to set a list of GitHub URLs in the template context so we can render
+    them in the sidebar. To get the GitHub url we use the ``rapids_deployment_notebooks_base_url`` config
+    option which shows the base url for where the source files are on GitHub.
+
+    """
+    if "examples/" in pagename and context["page_source_suffix"] == ".ipynb":
+        source_root = pathlib.Path(__file__).parent / ".." / "source"
+        base_url = app.config.rapids_deployment_notebooks_base_url
+        rel_page_parent = pathlib.Path(pagename).parent
+        path_to_page_parent = source_root / rel_page_parent
+
+        related_notebook_files = []
+        for page in path_to_page_parent.glob("*"):
+            if "ipynb" not in page.name:
+                related_notebook_files.append(
+                    f"{base_url}{rel_page_parent}/{page.name}"
+                )
+
+        context["related_notebook_files"] = related_notebook_files
+
+
+def setup(app):
+    app.add_config_value("rapids_deployment_notebooks_base_url", "", "html")
+    app.connect("html-page-context", find_notebook_related_files)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

source/_templates/notebooks-extra-files-nav.html

@@ -0,0 +1,16 @@
+{% if related_notebook_files %}
+<div class="tocsection onthispage">
+  <i class="fa-regular fa-file"></i> Related files
+</div>
+<nav id="bd-toc-nav" class="page-toc">
+  <ul class="visible nav section-nav flex-column">
+    {% for file in related_notebook_files %}
+    <li class="toc-h2 nav-item toc-entry">
+      <a class="reference external nav-link" href="{{ file }}">
+        {{ file.split("/")[-1] }}
+      </a>
+    </li>
+    {% endfor %}
+  </ul>
+</nav>
+{% endif %}

source/conf.py

@@ -10,17 +10,18 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../extensions"))
 import datetime
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'RAPIDS Deployment Documentation'
-copyright = f'{datetime.date.today().year}, NVIDIA'
-author = 'NVIDIA'
+project = "RAPIDS Deployment Documentation"
+copyright = f"{datetime.date.today().year}, NVIDIA"
+author = "NVIDIA"
 
 
 # -- General configuration ---------------------------------------------------
@@ -34,18 +35,25 @@
     "sphinxcontrib.mermaid",
     "sphinx_design",
     "sphinx_copybutton",
+    "rapids_notebook_files",
 ]
 
 myst_enable_extensions = ["colon_fence"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# -- Options for notebooks -------------------------------------------------
+
+nb_execution_mode = "off"
+rapids_deployment_notebooks_base_url = (
+    "https://github.com/rapidsai/deployment/blob/main/source/"
+)
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -55,18 +63,23 @@
     "twitter_url": "https://twitter.com/rapidsai",
     "show_toc_level": 1,
     "navbar_align": "right",
+    "secondary_sidebar_items": [
+        "page-toc",
+        "notebooks-extra-files-nav",
+    ],
 }
 
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-html_logo = '_static/RAPIDS-logo-purple.png'
+html_static_path = ["_static"]
+html_logo = "_static/RAPIDS-logo-purple.png"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
@@ -76,7 +89,10 @@
     "dask_cuda": ("https://docs.rapids.ai/api/dask-cuda/stable/", None),
 }
 
+
 def setup(app):
     app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")
-    app.add_js_file("https://docs.rapids.ai/assets/js/custom.js", loading_method="defer")
+    app.add_js_file(
+        "https://docs.rapids.ai/assets/js/custom.js", loading_method="defer"
+    )
     app.add_js_file("js/nav.js", loading_method="defer")

source/examples/index.md

@@ -0,0 +1,43 @@
+---
+html_theme.sidebar_secondary.remove: true
+---
+
+# Workflow Examples
+
+`````{grid} 1 2 2 3
+:gutter: 2 2 2 2
+
+````{grid-item-card}
+:link: xgboost-gpu-hpo-job-parallel-k8s/notebook
+:link-type: doc
+XGBoost HPO
+^^^
+Scaling up hyperparameter optimization with Kubernetes and XGBoost GPU algorithm
+
+{bdg-primary}`Dask`
+{bdg-primary}`XGBoost`
+{bdg-primary}`Kubernetes`
+````
+
+````{grid-item-card}
+:link: rapids-sagemaker-higgs/notebook
+:link-type: doc
+HPO on Sagemaker with cuML
+^^^
+Running RAPIDS hyperparameter experiments at scale on Amazon SageMaker
+
+{bdg-primary}`cuML`
+{bdg-primary}`Sagemaker`
+{bdg-primary}`AWS`
+````
+
+`````
+
+```{toctree}
+:maxdepth: 2
+:caption: Workflow Examples
+:hidden:
+
+xgboost-gpu-hpo-job-parallel-k8s/notebook
+rapids-sagemaker-higgs/notebook
+```

source/examples/rapids-sagemaker-higgs/Dockerfile

@@ -0,0 +1,12 @@
+# FROM rapidsai/rapidsai-cloud-ml:latest
+FROM rapidsai/rapidsai-nightly:22.12-cuda11.5-runtime-ubuntu18.04-py3.9
+
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential 
+
+RUN source activate rapids && pip install sagemaker-training 
+
+# Copies the training code inside the container
+COPY rapids-higgs.py /opt/ml/code/rapids-higgs.py
+
+# Defines rapids-higgs.py as script entry point
+ENV SAGEMAKER_PROGRAM rapids-higgs.py