Adds versioning to the docs (isaac-sim#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
kellyguo11 · Oct 18, 2024 · 0bccd88 · 0bccd88
1 parent a4118d7
commit 0bccd88
Show file tree

Hide file tree

Showing 12 changed files with 245 additions and 93 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -1,48 +1,57 @@
 name: Build & deploy docs
 
-on: [push]
+on:
+  push:
+  pull_request:
 
 jobs:
   build-docs:
     name: Build Docs
     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
     runs-on: ubuntu-latest
     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
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -28,6 +28,7 @@ Guidelines for modifications:
 * Mayank Mittal
 * Nikita Rudin
 * Pascal Roth
+* Sheikh Dawood
 
 ## Contributors
 

diff --git a/docs/Makefile b/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)
diff --git a/docs/README.md b/docs/README.md
@@ -1,30 +1,75 @@
 # 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>
diff --git a/docs/_redirect/index.html b/docs/_redirect/index.html
@@ -0,0 +1,8 @@
+<!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>
diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html
@@ -0,0 +1,21 @@
+{% 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 %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -54,6 +54,8 @@
     "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 @@
 # 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 @@
 
 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 @@
     "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 @@
     "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 -------------------------------------------------

diff --git a/docs/licenses/dependencies/sphinx-multiversion-license.txt b/docs/licenses/dependencies/sphinx-multiversion-license.txt
@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2020, Jan Holthuis <[email protected]>
+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.