Add linkcheck to docs, fix broken links (#83)

### What change is being made

Add linkcheck to docs workflow.
Fix links which were broken.

### Why this change is being made

Avoid broken links.

### Tested

```
pixi run -e docs linkcheck
✨ Pixi task (linkcheck in docs): sphinx-build -b linkcheck docs docs/_build/linkcheck               Running Sphinx v8.2.3
loading translations [en]... done
loading pickled environment... The configuration has changed (1 option: 'linkcheck_ignore')
done
myst v5.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=4, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [linkcheck]: targets for 8 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
preparing documents... done
copying assets...
copying assets: done
writing output... [100%] tutorial/exporter/exporter_tutorial

(tutorial/controller/controller_tutorial: line   18) -ignored- https://github.com/rai-inst/exploy/tree/main/examples/controller/
(tutorial/exporter/exporter_tutorial: line   20) -ignored- https://github.com/rai-inst/exploy/blob/main/python/exploy/exporter/core/tests/test_export_environment.py
(   api/core/core: line    1) ok        https://docs.python.org/3/library/abc.html#abc.ABC
(   api/core/core: line    8) ok        https://docs.python.org/3/library/constants.html#Ellipsis
(   api/core/core: line    8) ok        https://docs.python.org/3/library/constants.html#None
(   api/core/core: line    1) ok        https://docs.python.org/3/library/enum.html#enum.Enum
(   api/core/core: line    8) ok        https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable
(   api/core/core: line   51) ok        https://docs.python.org/3/library/exceptions.html#KeyError
(   api/core/core: line   51) ok        https://docs.python.org/3/library/exceptions.html#AssertionError
(   api/core/core: line   22) ok        https://docs.python.org/3/library/functions.html#bool
(   api/core/core: line   65) ok        https://docs.python.org/3/library/functions.html#float
(   api/core/core: line    1) ok        https://docs.python.org/3/library/functions.html#int
(   api/core/core: line   93) ok        https://docs.python.org/3/library/pathlib.html#pathlib.Path
(   api/core/core: line    1) ok        https://docs.python.org/3/library/functions.html#object
(   api/core/core: line   22) ok        https://docs.python.org/3/library/stdtypes.html#str
(   api/core/core: line    1) ok        https://docs.python.org/3/library/typing.html#typing.Any
(   api/core/core: line   22) ok        https://docs.python.org/3/library/stdtypes.html#list
(   api/core/core: line   22) ok        https://docs.python.org/3/library/stdtypes.html#dict
(   api/core/core: line    8) ok        https://docs.python.org/3/library/stdtypes.html#tuple
(   api/core/core: line    7) ok        https://docs.pytorch.org/docs/stable/notes/extending.html#extending-torch-python-api
(   api/core/core: line    1) ok        https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module
(   api/core/core: line    8) ok        https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor
(api/frameworks/isaaclab: line    6) ok        https://en.wikipedia.org/wiki/Angular_velocity#Spin_angular_velocity_of_a_rigid_body_or_reference_frame
(   api/core/core: line    1) ok        https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray
(   api/core/core: line   79) ok        https://onnxruntime.ai/docs/reference/compatibility.html
( getting_started: line   39) redirect  https://pixi.sh - permanently to https://pixi.prefix.dev/
(   api/core/core: line   10) ok        https://github.com/docarray/notes/blob/main/blog/02-this-weeks-in-docarray-01.md
(tutorial/exporter/exporter_tutorial: line  403) ok        https://github.com/lutzroeder/netron
build succeeded.

```

GitOrigin-RevId: 110c6c7222bc138e6350dd2db5dcd0daf4f24507

Author: awoll-bdai

.github/workflows/docs.yml

@@ -49,6 +49,9 @@ jobs:
       - name: Build Documentation
         run: pixi run -e docs build
 
+      - name: Check Links
+        run: pixi run -e docs linkcheck
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4
         with:

docs/conf.py

@@ -148,8 +148,27 @@ def add_eigen_links(app, doctree, docname):
                         break
 
 
+def fix_readme_doc_links(app, doctree):
+    """Strip the leading 'docs/' from doc links included from outside the Sphinx source tree.
+
+    Files like README.md use paths relative to the repo root (e.g. docs/tutorial/foo.md),
+    but Sphinx resolves links relative to the docs/ source directory, so the
+    prefix needs to be removed for internal cross-references to work.
+    """
+    from sphinx.addnodes import pending_xref
+
+    for node in doctree.traverse(pending_xref):
+        target = node.get("reftarget", "")
+        if target.startswith("docs/"):
+            target = target[len("docs/") :]
+            if target.endswith(".md"):
+                target = target[: -len(".md")]
+            node["reftarget"] = target
+
+
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member)
+    app.connect("doctree-read", fix_readme_doc_links)
     app.connect("doctree-resolved", add_eigen_links)
 
 
@@ -184,6 +203,17 @@ def setup(app):
 # resolve inside the Sphinx doc tree (e.g., README links to files at the repo root).
 suppress_warnings = ["myst.xref_missing"]
 
+# Links that are valid but not yet publicly available (e.g. unreleased paths on GitHub)
+linkcheck_ignore = [
+    # The repository is private; GitHub returns 404 for unauthenticated requests.
+    r"https://github\.com/bdaiinstitute/exploy/",
+]
+
+# GitHub renders anchors client-side, so Sphinx linkcheck cannot verify them.
+linkcheck_anchors_ignore_for_url = [
+    r"https://github\.com/",
+]
+
 # Note: Eigen uses Doxygen, not Sphinx, so intersphinx won't work.
 # For Eigen cross-references, use direct links or configure Doxygen tag files in breathe_doxygen_config_options
 

docs/getting_started.md

@@ -0,0 +1,4 @@
+# Getting Started
+
+```{include} ../README.md
+```

docs/getting_started.rst

@@ -18,7 +18,7 @@ By the end of this tutorial you will know how to:
 6. Validate the export by comparing ONNX outputs against the original environment.
 
 > **Note:** A complete, runnable version of the code in this tutorial is available as a test in
-> [`exploy/exporter/core/tests/test_export_environment.py`](https://github.com/bdaiinstitute/exploy/blob/main/exploy/exporter/core/tests/test_export_environment.py).
+> [`python/exploy/exporter/core/tests/test_export_environment.py`](https://github.com/bdaiinstitute/exploy/blob/main/python/exploy/exporter/core/tests/test_export_environment.py).
 > This tutorial explains the details behind that test step by step.
 
 ## Prerequisites

docs/tutorial/exporter/exporter_tutorial.md

@@ -146,6 +146,9 @@ doxygen = "mkdir -p docs/_build/doxygen && doxygen Doxyfile"
 build = { cmd = "sphinx-build -b html docs docs/_build/html", depends-on = [
   "doxygen",
 ] }
+linkcheck = { cmd = "sphinx-build -b linkcheck docs docs/_build/linkcheck", depends-on = [
+   "doxygen",
+]}
 clean = "rm -rf docs/_build"
 open = "xdg-open docs/_build/html/index.html || open docs/_build/html/index.html"