diff --git a/base_conf.py b/base_conf.py index 536b1cf3ad..9cd82d0526 100644 --- a/base_conf.py +++ b/base_conf.py @@ -40,9 +40,9 @@ templates_path = ["_templates"] -source_suffix = [ - ".md", -] +source_suffix = { + ".md": "markdown" +} myst_heading_anchors = 4 diff --git a/build_multiversion.py b/build_multiversion.py index 583b9630fb..294160086a 100644 --- a/build_multiversion.py +++ b/build_multiversion.py @@ -35,6 +35,31 @@ def _combine_nav(common_nav, release_nav): combined.insert(i + 1, item) return combined +def _build_sphinx(src_dir, output_dir, variables, extra_args, strict_mode=True): + """Build arguments for running sphinx-build + + Args: + src_dir (str): Source directory + output_dir (str): Output directory + variables (dict): Dictionary of variables passed with `-D` + extra_args (list): Extra arguments forwarded to sphinx + """ + sphinx_args = [ + "sphinx-build", + "--nitpicky", + "-b", + "dirhtml"] + if strict_mode: + sphinx_args.append("--fail-on-warning") + + sphinx_args.extend([str(src_dir), str(output_dir)]) + + for key, val in variables.items(): + sphinx_args.extend(["-D", f"{key}={val}"]) + + sphinx_args.extend(extra_args) + + subprocess.run(sphinx_args, check=True) def copy_pages(pages, root_src_dir, dst): for page in pages: @@ -331,14 +356,9 @@ def build_libs(gz_nav_yaml, src_dir, tmp_dir, build_dir): generate_libs(gz_nav_yaml, libs_dir) - sphinx_args = [ - "sphinx-build", - "-b", - "dirhtml", - f"{libs_dir}", - f"{build_dir}", - ] - subprocess.run(sphinx_args) + # TODO(azeey) There are a few reference errors in the README files of some + # of the libraries, so we can't enable strict_mode yet. + _build_sphinx(libs_dir, build_dir, {}, [], strict_mode=False) def main(argv=None): @@ -396,19 +416,12 @@ def main(argv=None): for release in args.releases: generate_sources(gz_nav_yaml, src_dir, tmp_dir, release) release_build_dir = build_docs_dir / release - sphinx_args = [ - "sphinx-build", - "-b", - "dirhtml", - f"{tmp_dir/release}", - f"{release_build_dir }", - "-D", - f"gz_release={release}", - "-D", - f"gz_root_index_file={index_yaml}", - *unknown_args, - ] - subprocess.run(sphinx_args) + _build_sphinx( + tmp_dir / release, + release_build_dir, + {"gz_release": release, "gz_root_index_file": index_yaml}, + unknown_args, + ) # Handle "latest" and "all" release = preferred_release["name"] @@ -425,19 +438,12 @@ def main(argv=None): f"{pointer_tmp_dir} already exists and is not a symlink" ) - sphinx_args = [ - "sphinx-build", - "-b", - "dirhtml", - f"{pointer_tmp_dir}", - f"{release_build_dir}", - "-D", - f"gz_release={release}", - "-D", - f"gz_root_index_file={index_yaml}", - *unknown_args, - ] - subprocess.run(sphinx_args) + _build_sphinx( + pointer_tmp_dir, + release_build_dir, + {"gz_release": release, "gz_root_index_file": index_yaml}, + unknown_args, + ) # Create a redirect to "/latest" redirect_page = build_docs_dir / "index.html" diff --git a/conf.py b/conf.py index fd39723e2a..0a25c1f057 100644 --- a/conf.py +++ b/conf.py @@ -27,6 +27,7 @@ from sphinx.application import Sphinx from sphinx.config import Config +from pygments.lexers.shell import BatchLexer sys.path.append(str(Path(__file__).parent)) @@ -130,3 +131,4 @@ def setup(app: Sphinx): app.add_config_value("gz_root_index_file", "", rebuild="env", types=[str]) app.connect("html-page-context", setup_file_map) app.connect("config-inited", config_init) + app.add_lexer("cmd", BatchLexer) diff --git a/fortress/index.yaml b/fortress/index.yaml index 7cd7567852..28c445c85e 100644 --- a/fortress/index.yaml +++ b/fortress/index.yaml @@ -96,3 +96,6 @@ pages: - name: ros_gz_project_template_guide title: ROS 2 integration template file: ros_gz_project_template_guide.md + - name: web_visualization + title: Web Visualization + file: web_visualization.md diff --git a/garden/index.yaml b/garden/index.yaml index 820dd8b6a6..e0301c980f 100644 --- a/garden/index.yaml +++ b/garden/index.yaml @@ -94,3 +94,6 @@ pages: - name: ros_gz_project_template_guide title: ROS 2 integration template file: ros_gz_project_template_guide.md + - name: web_visualization + title: Web Visualization + file: web_visualization.md diff --git a/harmonic/index.yaml b/harmonic/index.yaml index 0ebfd3acb9..604c59f1e1 100644 --- a/harmonic/index.yaml +++ b/harmonic/index.yaml @@ -106,3 +106,6 @@ pages: - name: ros_gz_project_template_guide title: ROS 2 integration template file: ros_gz_project_template_guide.md + - name: web_visualization + title: Web Visualization + file: web_visualization.md diff --git a/ionic/index.yaml b/ionic/index.yaml index ef05c75cc7..b79b17f82f 100644 --- a/ionic/index.yaml +++ b/ionic/index.yaml @@ -106,3 +106,6 @@ pages: - name: ros_gz_project_template_guide title: ROS 2 integration template file: ros_gz_project_template_guide.md + - name: web_visualization + title: Web Visualization + file: web_visualization.md diff --git a/jetty/index.yaml b/jetty/index.yaml index b68921be90..f7ff342e13 100644 --- a/jetty/index.yaml +++ b/jetty/index.yaml @@ -109,3 +109,6 @@ pages: - name: ros_gz_project_template_guide title: ROS 2 integration template file: ros_gz_project_template_guide.md + - name: web_visualization + title: Web Visualization + file: web_visualization.md