Adds versioning to the docs (#1247)

# Description

Adds versioning to the docs. Users can now choose a specific tag from
version v1.0.0 onwards.

## Type of change

- New feature (non-breaking change which adds functionality)

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

.github/workflows/docs.yaml

 name: Build & deploy docs
 
-on: [push]
+on:
+  push:
+  pull_request:
 
 jobs:
   build-docs:
@@ -8,28 +10,35 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v2
+    - name: Checkout code
+      uses: actions/checkout@v2
 
-      - name: Setup python
-        uses: actions/setup-python@v2
-        with:
-          python-version: "3.10"
-          architecture: x64
+    - name: Setup python
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.10"
+        architecture: x64
 
-      - name: Install dev requirements
-        working-directory: ./docs
-        run: pip install -r requirements.txt
+    - name: Install dev requirements
+      working-directory: ./docs
+      run: pip install -r requirements.txt
 
-      - name: Generate docs
-        working-directory: ./docs
-        run: make html
+    - name: Check branch docs building
+      if: ${{ github.event_name == 'pull_request' }}
+      working-directory: ./docs
+      run: make current-docs
 
-      - name: Upload docs artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: docs-html
-          path: ./docs/_build/html
+    - name: Generate multi-version docs
+      working-directory: ./docs
+      run: |
+        git fetch --prune --unshallow --tags
+        make multi-docs
+
+    - name: Upload docs artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs-html
+        path: ./docs/_build
 
   check-secrets:
     name: Check secrets
@@ -37,12 +46,12 @@ jobs:
     outputs:
       trigger-deploy: ${{ steps.trigger-deploy.outputs.defined }}
     steps:
-      - id: trigger-deploy
-        env:
-          REPO_NAME: ${{ secrets.REPO_NAME }}
-          BRANCH_REF: ${{ secrets.BRANCH_REF }}
-        if: "${{ github.repository == env.REPO_NAME && github.ref == env.BRANCH_REF }}"
-        run: echo "defined=true" >> "$GITHUB_OUTPUT"
+    - id: trigger-deploy
+      env:
+        REPO_NAME: ${{ secrets.REPO_NAME }}
+        BRANCH_REF: ${{ secrets.BRANCH_REF }}
+      if: "${{ github.repository == env.REPO_NAME && github.ref == env.BRANCH_REF }}"
+      run: echo "defined=true" >> "$GITHUB_OUTPUT"
 
   deploy-docs:
     name: Deploy Docs
@@ -51,14 +60,14 @@ jobs:
     if: needs.check-secrets.outputs.trigger-deploy == 'true'
 
     steps:
-      - name: Download docs artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: docs-html
-          path: ./docs/_build/html
+    - name: Download docs artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: docs-html
+        path: ./docs/_build
 
-      - name: Deploy to gh-pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/_build/html
+    - name: Deploy to gh-pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build

CONTRIBUTORS.md

@@ -28,6 +28,7 @@ Guidelines for modifications:
 * Mayank Mittal
 * Nikita Rudin
 * Pascal Roth
+* Sheikh Dawood
 
 ## Contributors
 

docs/Makefile

@@ -8,13 +8,11 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: multi-docs
+multi-docs:
+	@sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@cp _redirect/index.html $(BUILDDIR)/index.html
 
-.PHONY: help Makefile
-
-# 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)
+.PHONY: current-docs
+current-docs:
+	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/current" $(SPHINXOPTS)

docs/README.md

 # Building Documentation
 
-We use [Sphinx](https://www.sphinx-doc.org/en/master/) with the [Book Theme](https://sphinx-book-theme.readthedocs.io/en/stable/) for maintaining the documentation.
+We use [Sphinx](https://www.sphinx-doc.org/en/master/) with the [Book Theme](https://sphinx-book-theme.readthedocs.io/en/stable/) for maintaining and generating our documentation.
 
-> **Note:** To build the documentation, we recommend creating a virtual environment to avoid any conflicts with system installed dependencies.
+> **Note:** To avoid dependency conflicts, we strongly recommend using a Python virtual environment to isolate the required dependencies from your system's global Python environment.
 
-Execute the following instructions to build the documentation (assumed from the top of the repository):
+## Current-Version Documentation
 
-1. Install the dependencies for [Sphinx](https://www.sphinx-doc.org/en/master/):
+This section describes how to build the documentation for the current version of the project.
 
-    ```bash
-    # enter the location where this readme exists
-    cd docs
-    # install dependencies
-    pip install -r requirements.txt
-    ```
+<details open>
+<summary><strong>Linux</strong></summary>
 
-2. Generate the documentation file via:
+```bash
+# 1. Navigate to the docs directory and install dependencies
+cd docs
+pip install -r requirements.txt
 
-    ```bash
-    # make the html version
-    make html
-    ```
+# 2. Build the current documentation
+make current-docs
 
-3. The documentation is now available at `docs/_build/html/index.html`:
+# 3. Open the current docs
+xdg-open _build/current/index.html
+```
+</details>
 
-    ```bash
-    # open on default browser
-    xdg-open _build/html/index.html
-    ```
+<details> <summary><strong>Windows</strong></summary>
+
+```batch
+:: 1. Navigate to the docs directory and install dependencies
+cd docs
+pip install -r requirements.txt
+
+:: 2. Build the current documentation
+make current-docs
+
+:: 3. Open the current docs
+start _build\current\index.html
+```
+</details>
+
+
+## Multi-Version Documentation
+
+This section describes how to build the multi-version documentation, which includes previous tags and the main branch.
+
+<details open> <summary><strong>Linux</strong></summary>
+
+```bash
+# 1. Navigate to the docs directory and install dependencies
+cd docs
+pip install -r requirements.txt
+
+# 2. Build the multi-version documentation
+make multi-docs
+
+# 3. Open the multi-version docs
+xdg-open _build/index.html
+```
+</details>
+
+<details> <summary><strong>Windows</strong></summary>
+
+```batch
+:: 1. Navigate to the docs directory and install dependencies
+cd docs
+pip install -r requirements.txt
+
+:: 2. Build the multi-version documentation
+make multi-docs
+
+:: 3. Open the multi-version docs
+start _build\index.html
+```
+</details>

docs/_redirect/index.html

+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to the latest Isaac Lab documentation</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+  </head>
+</html>

docs/_templates/versioning.html

+{% if versions %}
+<nav class="bd-links bd-docs-nav">
+    <div class="bd-toc-item navbar-nav">
+      <ul class="nav bd-sidenav">
+        <li class="toctree-l1 has-children" style="display: flex; justify-content: center; align-items: center; flex-direction: column;">
+          <div  style ="text-align:center;">
+            <label for="version-select" style="font-weight: bold; display: block;">Version</label>
+          </div>
+          <select id="version-select" class="version-dropdown" style="margin: 0 auto; display: block;" onchange="location = this.value;">
+            {%- for item in versions.branches %}
+            <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
+            {%- endfor %}
+            {%- for item in versions.tags|reverse %}
+            <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
+            {%- endfor %}
+          </select>
+        </li>
+      </ul>
+    </div>
+</nav>
+{% endif %}

docs/conf.py

@@ -54,6 +54,8 @@ extensions = [
     "sphinxcontrib.icon",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinx_tabs.tabs",  # backwards compatibility for building docs on v1.0.0
+    "sphinx_multiversion",
 ]
 
 # mathjax hacks
@@ -115,7 +117,7 @@ templates_path = []
 # 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 = ["_build", "Thumbs.db", ".DS_Store", "README.md", "licenses/*"]
+exclude_patterns = ["_build", "_redirect", "_templates", "Thumbs.db", ".DS_Store", "README.md", "licenses/*"]
 
 # Mock out modules that are not available on RTD
 autodoc_mock_imports = [
@@ -190,7 +192,7 @@ language = "en"
 
 import sphinx_book_theme
 
-html_title = "Isaac Lab documentation"
+html_title = "Isaac Lab Documentation"
 html_theme_path = [sphinx_book_theme.get_html_theme_path()]
 html_theme = "sphinx_book_theme"
 html_favicon = "source/_static/favicon.ico"
@@ -213,7 +215,7 @@ html_theme_options = {
     "show_toc_level": 1,
     "use_sidenotes": True,
     "logo": {
-        "text": "Isaac Lab documentation",
+        "text": "Isaac Lab Documentation",
         "image_light": "source/_static/NVIDIA-logo-white.png",
         "image_dark": "source/_static/NVIDIA-logo-black.png",
     },
@@ -240,7 +242,19 @@ html_theme_options = {
     "icon_links_label": "Quick Links",
 }
 
-html_sidebars = {"**": ["navbar-logo.html", "icon-links.html", "search-field.html", "sbt-sidebar-nav.html"]}
+templates_path = [
+    "_templates",
+]
+
+# Whitelist pattern for remotes
+smv_remote_whitelist = r"^.*$"
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = os.getenv("SMV_BRANCH_WHITELIST", r"^(main|devel)$")
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = os.getenv("SMV_TAG_WHITELIST", r"^v[1-9]\d*\.\d+\.\d+$")
+html_sidebars = {
+    "**": ["navbar-logo.html", "versioning.html", "icon-links.html", "search-field.html", "sbt-sidebar-nav.html"]
+}
 
 
 # -- Advanced configuration -------------------------------------------------

docs/licenses/dependencies/sphinx-multiversion-license.txt

+BSD 2-Clause License
+
+Copyright (c) 2020, Jan Holthuis <jan.holthuis@ruhr-uni-bochum.de>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/make.bat

@@ -2,34 +2,63 @@
 
 pushd %~dp0
 
-REM Command file for Sphinx documentation
+REM Command file to build Sphinx documentation
 
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
 set SOURCEDIR=.
 set BUILDDIR=_build
 
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
+REM Check if a specific target was passed
+if "%1" == "multi-docs" (
+	REM Check if SPHINXBUILD is set, if not default to sphinx-multiversion
+	if "%SPHINXBUILD%" == "" (
+		set SPHINXBUILD=sphinx-multiversion
+	)
+	%SPHINXBUILD% >NUL 2>NUL
+	if errorlevel 9009 (
+		echo.
+		echo.The 'sphinx-multiversion' command was not found. Make sure you have Sphinx
+		echo.installed, then set the SPHINXBUILD environment variable to point
+		echo.to the full path of the 'sphinx-multiversion' executable. Alternatively you
+		echo.may add the Sphinx directory to PATH.
+		echo.
+		echo.If you don't have Sphinx installed, grab it from
+		echo.http://sphinx-doc.org/
+		exit /b 1
+	)
+	%SPHINXBUILD% %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+	REM Copy the redirect index.html to the build directory
+	copy _redirect\index.html %BUILDDIR%\index.html
+	goto end
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
+if "%1" == "current-docs" (
+	REM Check if SPHINXBUILD is set, if not default to sphinx-build
+	if "%SPHINXBUILD%" == "" (
+		set SPHINXBUILD=sphinx-build
+	)
+	%SPHINXBUILD% >NUL 2>NUL
+	if errorlevel 9009 (
+		echo.
+		echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+		echo.installed, then set the SPHINXBUILD environment variable to point
+		echo.to the full path of the 'sphinx-build' executable. Alternatively you
+		echo.may add the Sphinx directory to PATH.
+		echo.
+		echo.If you don't have Sphinx installed, grab it from
+		echo.http://sphinx-doc.org/
+		exit /b 1
+	)
+	%SPHINXBUILD% %SOURCEDIR% %BUILDDIR%\current %SPHINXOPTS% %O%
+	goto end
+)
 
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+REM If no valid target is passed, show usage instructions
+echo.
+echo.Usage:
+echo.  make.bat multi-docs    - To build the multi-version documentation.
+echo.  make.bat current-docs  - To build the current documentation.
+echo.
 
 :end
 popd

docs/requirements.txt

@@ -7,6 +7,8 @@ sphinx-copybutton
 sphinx-icon
 sphinx_design
 sphinxemoji
+sphinx-tabs # backwards compatibility for building docs on v1.0.0
+sphinx-multiversion==0.2.4
 
 # basic python
 numpy

isaaclab.bat

@@ -519,9 +519,9 @@ if "%arg%"=="-i" (
     call :extract_python_exe
     pushd %ISAACLAB_PATH%\docs
     call !python_exe! -m pip install -r requirements.txt >nul
-    call !python_exe! -m sphinx -b html -d _build\doctrees . _build\html
+    call !python_exe! -m sphinx -b html -d _build\doctrees . _build\current
     echo [INFO] To open documentation on default browser, run:
-    echo xdg-open "%ISAACLAB_PATH%\docs\_build\html\index.html"
+    echo xdg-open "%ISAACLAB_PATH%\docs\_build\current\index.html"
     popd >nul
     shift
     goto :end

isaaclab.sh

@@ -396,10 +396,10 @@ while [[ $# -gt 0 ]]; do
             cd ${ISAACLAB_PATH}/docs
             ${python_exe} -m pip install -r requirements.txt > /dev/null
             # build the documentation
-            ${python_exe} -m sphinx -b html -d _build/doctrees . _build/html
+            ${python_exe} -m sphinx -b html -d _build/doctrees . _build/current
             # open the documentation
             echo -e "[INFO] To open documentation on default browser, run:"
-            echo -e "\n\t\txdg-open $(pwd)/_build/html/index.html\n"
+            echo -e "\n\t\txdg-open $(pwd)/_build/current/index.html\n"
             # exit neatly
             cd - > /dev/null
             shift # past argument