Skip to content

Commit 6068b48

Browse files
sheikh-nvsheikh-nv
authored
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
1 parent 5036688 commit 6068b48

File tree

12 files changed

+245
-93
lines changed

12 files changed

+245
-93
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 44 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,57 @@
11
name: Build & deploy docs
22

3-
on: [push]
3+
on:
4+
push:
5+
pull_request:
46

57
jobs:
68
build-docs:
79
name: Build Docs
810
runs-on: ubuntu-latest
911

1012
steps:
11-
- name: Checkout code
12-
uses: actions/checkout@v2
13+
- name: Checkout code
14+
uses: actions/checkout@v2
1315

14-
- name: Setup python
15-
uses: actions/setup-python@v2
16-
with:
17-
python-version: "3.10"
18-
architecture: x64
16+
- name: Setup python
17+
uses: actions/setup-python@v2
18+
with:
19+
python-version: "3.10"
20+
architecture: x64
1921

20-
- name: Install dev requirements
21-
working-directory: ./docs
22-
run: pip install -r requirements.txt
22+
- name: Install dev requirements
23+
working-directory: ./docs
24+
run: pip install -r requirements.txt
2325

24-
- name: Generate docs
25-
working-directory: ./docs
26-
run: make html
26+
- name: Check branch docs building
27+
if: ${{ github.event_name == 'pull_request' }}
28+
working-directory: ./docs
29+
run: make current-docs
2730

28-
- name: Upload docs artifact
29-
uses: actions/upload-artifact@v4
30-
with:
31-
name: docs-html
32-
path: ./docs/_build/html
31+
- name: Generate multi-version docs
32+
working-directory: ./docs
33+
run: |
34+
git fetch --prune --unshallow --tags
35+
make multi-docs
36+
37+
- name: Upload docs artifact
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: docs-html
41+
path: ./docs/_build
3342

3443
check-secrets:
3544
name: Check secrets
3645
runs-on: ubuntu-latest
3746
outputs:
3847
trigger-deploy: ${{ steps.trigger-deploy.outputs.defined }}
3948
steps:
40-
- id: trigger-deploy
41-
env:
42-
REPO_NAME: ${{ secrets.REPO_NAME }}
43-
BRANCH_REF: ${{ secrets.BRANCH_REF }}
44-
if: "${{ github.repository == env.REPO_NAME && github.ref == env.BRANCH_REF }}"
45-
run: echo "defined=true" >> "$GITHUB_OUTPUT"
49+
- id: trigger-deploy
50+
env:
51+
REPO_NAME: ${{ secrets.REPO_NAME }}
52+
BRANCH_REF: ${{ secrets.BRANCH_REF }}
53+
if: "${{ github.repository == env.REPO_NAME && github.ref == env.BRANCH_REF }}"
54+
run: echo "defined=true" >> "$GITHUB_OUTPUT"
4655

4756
deploy-docs:
4857
name: Deploy Docs
@@ -51,14 +60,14 @@ jobs:
5160
if: needs.check-secrets.outputs.trigger-deploy == 'true'
5261

5362
steps:
54-
- name: Download docs artifact
55-
uses: actions/download-artifact@v4
56-
with:
57-
name: docs-html
58-
path: ./docs/_build/html
63+
- name: Download docs artifact
64+
uses: actions/download-artifact@v4
65+
with:
66+
name: docs-html
67+
path: ./docs/_build
5968

60-
- name: Deploy to gh-pages
61-
uses: peaceiris/actions-gh-pages@v3
62-
with:
63-
github_token: ${{ secrets.GITHUB_TOKEN }}
64-
publish_dir: ./docs/_build/html
69+
- name: Deploy to gh-pages
70+
uses: peaceiris/actions-gh-pages@v3
71+
with:
72+
github_token: ${{ secrets.GITHUB_TOKEN }}
73+
publish_dir: ./docs/_build

‎CONTRIBUTORS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Guidelines for modifications:
2828
* Mayank Mittal
2929
* Nikita Rudin
3030
* Pascal Roth
31+
* Sheikh Dawood
3132

3233
## Contributors
3334

‎docs/Makefile‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,11 @@ SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = .
99
BUILDDIR = _build
1010

11-
# Put it first so that "make" without argument is like "make help".
12-
help:
13-
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
11+
.PHONY: multi-docs
12+
multi-docs:
13+
@sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
14+
@cp _redirect/index.html $(BUILDDIR)/index.html
1415

15-
.PHONY: help Makefile
16-
17-
# Catch-all target: route all unknown targets to Sphinx using the new
18-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19-
%: Makefile
20-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16+
.PHONY: current-docs
17+
current-docs:
18+
@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/current" $(SPHINXOPTS)

‎docs/README.md‎

Lines changed: 65 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,75 @@
11
# Building Documentation
22

3-
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.
3+
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.
44

5-
> **Note:** To build the documentation, we recommend creating a virtual environment to avoid any conflicts with system installed dependencies.
5+
> **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.
66
7-
Execute the following instructions to build the documentation (assumed from the top of the repository):
7+
## Current-Version Documentation
88

9-
1. Install the dependencies for [Sphinx](https://www.sphinx-doc.org/en/master/):
9+
This section describes how to build the documentation for the current version of the project.
1010

11-
```bash
12-
# enter the location where this readme exists
13-
cd docs
14-
# install dependencies
15-
pip install -r requirements.txt
16-
```
11+
<details open>
12+
<summary><strong>Linux</strong></summary>
1713

18-
2. Generate the documentation file via:
14+
```bash
15+
# 1. Navigate to the docs directory and install dependencies
16+
cd docs
17+
pip install -r requirements.txt
1918

20-
```bash
21-
# make the html version
22-
make html
23-
```
19+
# 2. Build the current documentation
20+
make current-docs
2421

25-
3. The documentation is now available at `docs/_build/html/index.html`:
22+
# 3. Open the current docs
23+
xdg-open _build/current/index.html
24+
```
25+
</details>
2626

27-
```bash
28-
# open on default browser
29-
xdg-open _build/html/index.html
30-
```
27+
<details> <summary><strong>Windows</strong></summary>
28+
29+
```batch
30+
:: 1. Navigate to the docs directory and install dependencies
31+
cd docs
32+
pip install -r requirements.txt
33+
34+
:: 2. Build the current documentation
35+
make current-docs
36+
37+
:: 3. Open the current docs
38+
start _build\current\index.html
39+
```
40+
</details>
41+
42+
43+
## Multi-Version Documentation
44+
45+
This section describes how to build the multi-version documentation, which includes previous tags and the main branch.
46+
47+
<details open> <summary><strong>Linux</strong></summary>
48+
49+
```bash
50+
# 1. Navigate to the docs directory and install dependencies
51+
cd docs
52+
pip install -r requirements.txt
53+
54+
# 2. Build the multi-version documentation
55+
make multi-docs
56+
57+
# 3. Open the multi-version docs
58+
xdg-open _build/index.html
59+
```
60+
</details>
61+
62+
<details> <summary><strong>Windows</strong></summary>
63+
64+
```batch
65+
:: 1. Navigate to the docs directory and install dependencies
66+
cd docs
67+
pip install -r requirements.txt
68+
69+
:: 2. Build the multi-version documentation
70+
make multi-docs
71+
72+
:: 3. Open the multi-version docs
73+
start _build\index.html
74+
```
75+
</details>

‎docs/_redirect/index.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Redirecting to the latest Isaac Lab documentation</title>
5+
<meta charset="utf-8">
6+
<meta http-equiv="refresh" content="0; url=./main/index.html">
7+
</head>
8+
</html>

‎docs/_templates/versioning.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{% if versions %}
2+
<nav class="bd-links bd-docs-nav">
3+
<div class="bd-toc-item navbar-nav">
4+
<ul class="nav bd-sidenav">
5+
<li class="toctree-l1 has-children" style="display: flex; justify-content: center; align-items: center; flex-direction: column;">
6+
<div style ="text-align:center;">
7+
<label for="version-select" style="font-weight: bold; display: block;">Version</label>
8+
</div>
9+
<select id="version-select" class="version-dropdown" style="margin: 0 auto; display: block;" onchange="location = this.value;">
10+
{%- for item in versions.branches %}
11+
<option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
12+
{%- endfor %}
13+
{%- for item in versions.tags|reverse %}
14+
<option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
15+
{%- endfor %}
16+
</select>
17+
</li>
18+
</ul>
19+
</div>
20+
</nav>
21+
{% endif %}

‎docs/conf.py‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@
5454
"sphinxcontrib.icon",
5555
"sphinx_copybutton",
5656
"sphinx_design",
57+
"sphinx_tabs.tabs", # backwards compatibility for building docs on v1.0.0
58+
"sphinx_multiversion",
5759
]
5860

5961
# mathjax hacks
@@ -115,7 +117,7 @@
115117
# List of patterns, relative to source directory, that match files and
116118
# directories to ignore when looking for source files.
117119
# This pattern also affects html_static_path and html_extra_path.
118-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md", "licenses/*"]
120+
exclude_patterns = ["_build", "_redirect", "_templates", "Thumbs.db", ".DS_Store", "README.md", "licenses/*"]
119121

120122
# Mock out modules that are not available on RTD
121123
autodoc_mock_imports = [
@@ -190,7 +192,7 @@
190192

191193
import sphinx_book_theme
192194

193-
html_title = "Isaac Lab documentation"
195+
html_title = "Isaac Lab Documentation"
194196
html_theme_path = [sphinx_book_theme.get_html_theme_path()]
195197
html_theme = "sphinx_book_theme"
196198
html_favicon = "source/_static/favicon.ico"
@@ -213,7 +215,7 @@
213215
"show_toc_level": 1,
214216
"use_sidenotes": True,
215217
"logo": {
216-
"text": "Isaac Lab documentation",
218+
"text": "Isaac Lab Documentation",
217219
"image_light": "source/_static/NVIDIA-logo-white.png",
218220
"image_dark": "source/_static/NVIDIA-logo-black.png",
219221
},
@@ -240,7 +242,19 @@
240242
"icon_links_label": "Quick Links",
241243
}
242244

243-
html_sidebars = {"**": ["navbar-logo.html", "icon-links.html", "search-field.html", "sbt-sidebar-nav.html"]}
245+
templates_path = [
246+
"_templates",
247+
]
248+
249+
# Whitelist pattern for remotes
250+
smv_remote_whitelist = r"^.*$"
251+
# Whitelist pattern for branches (set to None to ignore all branches)
252+
smv_branch_whitelist = os.getenv("SMV_BRANCH_WHITELIST", r"^(main|devel)$")
253+
# Whitelist pattern for tags (set to None to ignore all tags)
254+
smv_tag_whitelist = os.getenv("SMV_TAG_WHITELIST", r"^v[1-9]\d*\.\d+\.\d+$")
255+
html_sidebars = {
256+
"**": ["navbar-logo.html", "versioning.html", "icon-links.html", "search-field.html", "sbt-sidebar-nav.html"]
257+
}
244258

245259

246260
# -- Advanced configuration -------------------------------------------------

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
BSD 2-Clause License
2+
3+
Copyright (c) 2020, Jan Holthuis <[email protected]>
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
20+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

0 commit comments

Comments
 (0)