docs: add sphinx-copybutton and sphinx-codeautolink

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_autorun",
     "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 = [