docs: init documentation versioning (#296)

Ref: #295

.github/workflows/documentation.yml

@@ -31,13 +31,15 @@ jobs:
     - name: Install dependencies
       run: poetry install --no-interaction --all-extras
     - name: Build documentation
-      run: poetry run poe docs --type build
+      run: |
+        poetry run poe docs --type build
+        touch documentation/build/.nojekyll
     - name: Setup Pages
-      uses: actions/configure-pages@v3
+      uses: actions/configure-pages@v4
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v1
       with:
-        path: "documentation/build/html"
+        path: "documentation/build"
   deploy:
     environment:
       name: github-pages

documentation/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= sphinx-multiversion
 SOURCEDIR     = source
 BUILDDIR      = build
 
@@ -20,4 +20,4 @@ apidoc: ; sphinx-apidoc -f --separate --module-first -o source/rst_source ../src
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/source/404.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. _404:
+
+404: Page Not Found
+===================
+
+Oops! The page you are looking for cannot be found.
+
+Please continue to the :doc:`Home Page <index>`.

documentation/source/_templates/page.html

@@ -0,0 +1,19 @@
+{% extends "!page.html" %}
+{% block body %}
+{% if current_version and latest_version and current_version != latest_version %}
+<div class="announcement">
+  <div class="announcement-content">
+    <strong>
+      {% if current_version.is_released %}
+      You're reading an old version of this documentation.
+      If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+      {% else %}
+      You're reading the documentation for a development version.
+      For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+      {% endif %}
+    </strong>
+  </div>
+</div>
+{% endif %}
+{{ super() }}
+{% endblock %}%

documentation/source/_templates/versioning.html

@@ -0,0 +1,16 @@
+{% if versions %}
+<div class="sidebar-tree">
+  <p class="caption" role="heading"><span class="caption-text">{{ _('Versions') }}</span></p>
+  <ul>
+    {%- for item in versions.in_development + versions.releases|sort(attribute='name', reverse=true) %}
+    {% set is_active = current_version.name == item.name %}
+    {% set is_unreleased = not item.is_released %}
+    <li class="toctree-l1 {% if is_active %}current current-page{% endif %}">
+      <a class="reference internal {% if is_active %}current{% endif %}" href="{{ item.url }}">
+        {{ item.name }} {% if is_unreleased %}(unreleased){% endif %}
+      </a>
+    </li>
+    {%- endfor %}
+  </ul>
+</div>
+{% endif %}

documentation/source/conf.py

@@ -20,7 +20,6 @@ def setup_paths():
 
 setup_paths()
 
-from genai import __version__  # noqa: E402
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -33,6 +32,8 @@ def setup_paths():
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    "sphinx_copybutton",
+    "notfound.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
@@ -51,6 +52,7 @@ def setup_paths():
     "sphinx.ext.viewcode",
     "sphinxcontrib.autodoc_pydantic",
     "sphinx_toolbox.collapse",
+    "sphinx_multiversion",
 ]
 
 napoleon_use_admonition_for_examples = True
@@ -59,8 +61,42 @@ def setup_paths():
 
 autosectionlabel_prefix_document = True
 templates_path = ["_templates"]
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "versioning.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html",
+    ]
+}
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r"^.*$"
+smv_branch_whitelist = os.environ["CURRENT_BRANCH"]
+smv_released_pattern = r"^refs/tags/.*$"
+smv_latest_version = os.environ["LATEST_VERSION"]
+notfound_urls_prefix = f"/{smv_latest_version}/"
+notfound_template = "page.html"
+version = smv_latest_version.replace("v", "")
+release = version
+smv_prebuild_command = " && ".join(
+    [
+        "cd ..",  # go to the project root
+        "make -C documentation/ apidoc",  # generates `modules` index
+        " ".join(
+            [
+                "PYTHONPATH='scripts'",
+                "BRANCH_NAME=$(cat ../versions.json | jq -r --arg DIR_NAME `basename $PWD` '.[] | select(.basedir | endswith($DIR_NAME)) | .name')",  # noqa
+                "python scripts/docs_examples_generator/main.py",
+                "scripts/docs_fix_schema_private.sh",
+            ]
+        ),
+    ]
+)
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content
 autoclass_content = "class"
 
@@ -96,7 +132,6 @@ def setup_paths():
 # html_theme = "alabaster"
 html_static_path = ["_static"]
 html_title = "IBM Generative AI Python SDK (Tech Preview)"
-release = __version__
 
 html_theme_options = {
     "light_css_variables": {