docs: add sphinx-copybutton and sphinx-codeautolink (#223)

## Summary

Brings SMTB's docs config in line with RTB and MVTB, which both already
have these two extensions:

- `sphinx-copybutton`: adds a copy button to code blocks, stripping
interactive `>>> `/`... `/`$ ` prompts so copied code actually runs.
- `sphinx-codeautolink`: turns code identifiers in examples into links
to their API docs.

Config (extensions list, `suppress_warnings` for codeautolink's own
match warnings, `copybutton_prompt_text`/etc.,
`codeautolink_custom_blocks`/`codeautolink_search_css_classes`) mirrors
RTB's `conf.py` exactly.

Also fixes a small pre-existing formatting wart in `intro.rst`: two `..
code-block:: python` blocks had `:linenos:` indented 3 spaces against
4-space code content. Plain docutils tolerated this silently, but
`sphinx-codeautolink`'s own parsing pass over code blocks is stricter
and surfaced it as a new "unexpected indent" warning -- fixed rather
than left as a regression.

## Test plan

- [x] Real `sphinx-build -b html`, isolated venv, against both master
and this branch
- [x] Warning count identical before/after: 14 warnings both times, same
content

Author: petercorke

docs/source/conf.py

@@ -15,6 +15,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 # sys.path.insert(0, os.path.abspath('..'))
 
+from sphinx_codeautolink import clean_ipython, clean_pycon
 
 # -- Project information -----------------------------------------------------
 
@@ -50,6 +51,14 @@
     "sphinx_pyrunblock",
     "sphinx.ext.intersphinx",
     "sphinx_favicon",
+    "sphinx_copybutton",
+    "sphinx_codeautolink",
+]
+
+suppress_warnings = [
+    "codeautolink.match_block",
+    "codeautolink.match_name",
+    "config.cache",  # codeautolink_custom_blocks holds function refs, not picklable
 ]
 #'sphinx.ext.autosummary',
 # typehints_use_signature_return = True
@@ -184,6 +193,24 @@
 np.set_printoptions(precision=4, suppress=True)
 """
 
+# -------- sphinx-codeautolink options --------------------------------------------#
+
+codeautolink_custom_blocks = {
+    "pycon": clean_pycon,
+    "ipython": clean_ipython,
+    "ipython3": clean_ipython,
+}
+# Ensure pycon (Python console) blocks are included in the autolink search.
+codeautolink_search_css_classes = ["highlight-python", "highlight-pycon"]
+
+# -------- sphinx-copybutton options ----------------------------------------------#
+# Strip interactive prompts (Python and shell) when users copy code snippets.
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = False
+copybutton_remove_prompts = True
+
 intersphinx_mapping = {
     "numpy": ("http://docs.scipy.org/doc/numpy/", None),
     "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),

docs/source/intro.rst

@@ -629,7 +629,7 @@ Graphics
 If ``matplotlib`` is installed then we can add 2D coordinate frames to a figure in a variety of styles:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     >>> trplot2( transl2(1,2), frame='A', rviz=True, width=1)
     >>> trplot2( transl2(3,1), color='red', arrow=True, width=3, frame='B')
@@ -646,7 +646,7 @@ If a figure does not yet exist one is added.  If a figure exists but there is no
 Similarly, we can plot 3D coordinate frames in a variety of styles:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     >>> trplot( transl(1,2,3), frame='A', rviz=True, width=1, dims=[0, 10, 0, 10, 0, 10])
     >>> trplot( transl(3,1, 2), color='red', width=3, frame='B')

pyproject.toml

@@ -65,6 +65,8 @@ docs = [
     "sphinxcontrib-jsmath",
     "sphinx-favicon",
     "sphinx-autodoc-typehints",
+    "sphinx-copybutton",
+    "sphinx-codeautolink",
 ]
 
 ros-humble = [