Skip to content

Commit 1aef31b

Browse files
urfeexurfeex
authored
Add support for multiversion (#18)
* Add support for multiversion * Save result as an artifact * Add distro name to output of build script * Remove Humble from multi-version build The Humble documentation is too different to include it currently.
1 parent 733eab3 commit 1aef31b

10 files changed

Lines changed: 225 additions & 15 deletions

File tree

‎.github/workflows/sphinx_build.yml‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,16 @@ jobs:
2626
python -m pip install --upgrade pip
2727
pip install -r requirements.txt
2828
pip install vcstool
29-
- name: Clone subrepos
29+
- name: Build documentation (all ROS 2 distros)
3030
run: |
3131
mkdir -p doc
32-
vcs import --input rolling.repos doc
33-
- name: Build documentation
34-
run: |
35-
make html
32+
bash scripts/build_docs.sh
33+
- name: Upload HTML documentation artifact
34+
if: success()
35+
uses: actions/upload-artifact@v4
36+
with:
37+
name: documentation-html
38+
path: _build/html
3639
- name: clone gh-pages branch
3740
uses: actions/checkout@v4
3841
if: ${{ success() && github.event_name != 'pull_request' && !env.ACT }}

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
11
_build/*
22
.venv
33
*.pyc
4+
5+
# vcstool clones (see *.repos)
6+
doc/ur_client_library/
7+
doc/ur_description/
8+
doc/ur_robot_driver/
9+
doc/ur_simulation_gz/
10+
doc/ur_tutorials/

‎Makefile‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,29 @@ SPHINXBUILD = sphinx-build
77
SOURCEDIR = .
88
BUILDDIR = _build
99

10+
SUBREPOS = doc/ur_client_library doc/ur_description doc/ur_robot_driver doc/ur_simulation_gz doc/ur_tutorials
11+
1012
# Put it first so that "make" without argument is like "make help".
1113
help:
1214
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1315

14-
.PHONY: help Makefile
16+
.PHONY: help Makefile html html-all clone-subrepos
17+
18+
# Clone subrepos for ROS_DISTRO (default: rolling). Requires vcstool.
19+
clone-subrepos:
20+
rm -rf $(SUBREPOS)
21+
ros=$${ROS_DISTRO:-rolling}; \
22+
vcs import --input $$ros.repos doc
23+
24+
# Single-distro HTML at _build/html/$(ROS_DISTRO)/ (default: rolling)
25+
html: clone-subrepos
26+
@ros=$${ROS_DISTRO:-rolling}; \
27+
export ROS_DISTRO="$$ros"; \
28+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/$$ros" $(SPHINXOPTS) $(O)
29+
30+
# Humble, Jazzy, Kilted, Rolling; optional root index redirect (see script)
31+
html-all:
32+
@./scripts/build_docs.sh
1533

1634
# Catch-all target: route all unknown targets to Sphinx using the new
1735
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

‎_templates/versions.html‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{# Read the Docs injects a version menu when READTHEDOCS is set; for GitHub Pages
2+
and local multi-distro builds we show the same UI when ``versions`` is set in
3+
html-page-context (see conf.py). #}
4+
{% if versions %}
5+
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Versions') }}">
6+
<span class="rst-current-version" data-toggle="rst-current-version">
7+
<span class="fa fa-book"> ROS 2</span>
8+
{{ current_version }}
9+
<span class="fa fa-caret-down"></span>
10+
</span>
11+
<div class="rst-other-versions">
12+
<dl>
13+
<dt>{{ _('Versions') }}</dt>
14+
{% for label, url in versions %}
15+
<dd><a href="{{ url }}">{{ label }}</a></dd>
16+
{% endfor %}
17+
</dl>
18+
</div>
19+
</div>
20+
{% endif %}

‎conf.py‎

Lines changed: 46 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
# full list see the documentation:
77
# http://www.sphinx-doc.org/en/master/config
88

9+
import os
10+
911
# -- Path setup --------------------------------------------------------------
1012

1113
# If extensions (or modules to document with autodoc) are in another directory,
@@ -23,8 +25,7 @@
2325
copyright = "2024, Universal Robots A/S"
2426
author = "Universal Robots A/S"
2527

26-
# The short X.Y version
27-
version = ""
28+
# The short X.Y version (shown in the sidebar; per-distro label)
2829
# The full version, including alpha/beta/rc tags
2930
release = "0.1"
3031

@@ -58,10 +59,33 @@
5859
master_doc = "index"
5960
numfig = True
6061

61-
ros_distro = "rolling"
62-
distro_title = "Rolling"
63-
distro_title_full = "Rolling Ridley"
64-
repos_file_branch = "main"
62+
# ROS 2 distribution for this HTML build: humble | jazzy | kilted | rolling
63+
# Set by scripts/build_docs.sh (or export ROS_DISTRO=... before sphinx-build).
64+
ros_distro = os.environ.get("ROS_DISTRO", "rolling").lower()
65+
66+
_distro_meta = {
67+
# "humble": ("Humble", "Humble Hawksbill"),
68+
"jazzy": ("Jazzy", "Jazzy Jalisco"),
69+
"kilted": ("Kilted", "Kilted Kaiju"),
70+
"rolling": ("Rolling", "Rolling Ridley"),
71+
}
72+
if ros_distro not in _distro_meta:
73+
raise ValueError(
74+
f"Unknown ROS_DISTRO={ros_distro!r}; expected one of: {', '.join(sorted(_distro_meta))}"
75+
)
76+
distro_title, distro_title_full = _distro_meta[ros_distro]
77+
version = distro_title
78+
79+
# Branch of *this* documentation repo for "Edit on GitHub" links
80+
repos_file_branch = os.environ.get("DOCUMENTATION_GIT_BRANCH", "main")
81+
82+
# Pairs (slug, label) for the floating version switcher (paths under _build/html/)
83+
_DOCUMENTATION_VERSION_SLUGS = (
84+
# ("humble", "Humble"),
85+
("jazzy", "Jazzy"),
86+
("kilted", "Kilted"),
87+
("rolling", "Rolling"),
88+
)
6589

6690
# The language for content autogenerated by Sphinx. Refer to documentation
6791
# for a list of supported languages.
@@ -93,9 +117,6 @@
93117
# Theme options are theme-specific and customize the look and feel of a theme
94118
# further. For a list of options available for each theme, see the
95119
# documentation.
96-
#
97-
# html_theme_options = {}
98-
99120
# Add any paths that contain custom static files (such as style sheets) here,
100121
# relative to this directory. They are copied after the builtin static files,
101122
# so a file named "default.css" will overwrite the builtin "default.css".
@@ -216,3 +237,19 @@
216237
]
217238

218239
github_url = "https://github.com/UniversalRobots/Universal_Robots_ROS_Documentation"
240+
241+
242+
def _html_page_context(app, pagename, templatename, context, doctree):
243+
"""Relative links to the same page under other distro output directories."""
244+
depth = 1 + pagename.count("/")
245+
prefix = "../" * depth
246+
context["versions"] = [
247+
(label, f"{prefix}{slug}/{pagename}.html")
248+
for slug, label in _DOCUMENTATION_VERSION_SLUGS
249+
]
250+
context["current_version"] = distro_title
251+
252+
253+
def setup(app):
254+
app.connect("html-page-context", _html_page_context)
255+
return {"parallel_read_safe": True, "parallel_write_safe": True}

‎humble.repos‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
repositories:
2+
ur_client_library:
3+
type: git
4+
url: https://github.com/UniversalRobots/Universal_Robots_Client_Library.git
5+
version: master
6+
ur_description:
7+
type: git
8+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Description.git
9+
version: humble
10+
ur_robot_driver:
11+
type: git
12+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
13+
version: humble
14+
ur_simulation_gz:
15+
type: git
16+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_GZ_Simulation.git
17+
version: humble
18+
ur_tutorials:
19+
type: git
20+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials.git
21+
version: humble

‎jazzy.repos‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
repositories:
2+
ur_client_library:
3+
type: git
4+
url: https://github.com/UniversalRobots/Universal_Robots_Client_Library.git
5+
version: master
6+
ur_description:
7+
type: git
8+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Description.git
9+
version: jazzy
10+
ur_robot_driver:
11+
type: git
12+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
13+
version: jazzy
14+
ur_simulation_gz:
15+
type: git
16+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_GZ_Simulation.git
17+
version: ros2
18+
ur_tutorials:
19+
type: git
20+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials.git
21+
version: main

‎kilted.repos‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
repositories:
2+
ur_client_library:
3+
type: git
4+
url: https://github.com/UniversalRobots/Universal_Robots_Client_Library.git
5+
version: master
6+
ur_description:
7+
type: git
8+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Description.git
9+
version: rolling
10+
ur_robot_driver:
11+
type: git
12+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
13+
version: kilted
14+
ur_simulation_gz:
15+
type: git
16+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_GZ_Simulation.git
17+
version: ros2
18+
ur_tutorials:
19+
type: git
20+
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials.git
21+
version: main

‎rolling.repos‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ repositories:
1919
type: git
2020
url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials.git
2121
version: main
22+

‎scripts/build_docs.sh‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
#!/usr/bin/env bash
2+
# Build Sphinx HTML for one or all ROS 2 distributions. Each distro uses the
3+
# matching *.repos file (branch pins per subrepository) and writes to
4+
# _build/html/<distro>/.
5+
set -euo pipefail
6+
7+
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
8+
cd "$ROOT"
9+
10+
SUBREPOS=(
11+
doc/ur_client_library
12+
doc/ur_description
13+
doc/ur_robot_driver
14+
doc/ur_simulation_gz
15+
doc/ur_tutorials
16+
)
17+
18+
DISTROS=(jazzy kilted rolling)
19+
REDIRECT_TARGET="${DOCUMENTATION_ROOT_REDIRECT:-rolling}"
20+
21+
clean_subrepos() {
22+
rm -rf "${SUBREPOS[@]}"
23+
}
24+
25+
build_one() {
26+
local distro="$1"
27+
export ROS_DISTRO="$distro"
28+
echo -e "\n\n====== Building documentation for ROS 2 distro: ${distro} ======\n"
29+
clean_subrepos
30+
vcs import --input "${distro}.repos" doc
31+
sphinx-build -b html . "${ROOT}/_build/html/${distro}"
32+
}
33+
34+
write_root_redirect() {
35+
local target="$1"
36+
cat > "${ROOT}/_build/html/index.html" <<EOF
37+
<!DOCTYPE html>
38+
<html lang="en">
39+
<head>
40+
<meta charset="utf-8">
41+
<meta http-equiv="refresh" content="0; url=${target}/index.html">
42+
<link rel="canonical" href="${target}/index.html">
43+
<title>Universal Robots ROS 2 Driver Documentation</title>
44+
</head>
45+
<body>
46+
<p><a href="${target}/index.html">Continue to ${target} documentation</a>.</p>
47+
</body>
48+
</html>
49+
EOF
50+
}
51+
52+
if [[ $# -eq 0 ]]; then
53+
for d in "${DISTROS[@]}"; do
54+
build_one "$d"
55+
done
56+
write_root_redirect "$REDIRECT_TARGET"
57+
else
58+
for d in "$@"; do
59+
build_one "$d"
60+
done
61+
fi

0 commit comments

Comments
 (0)