docs: Tweak admonition style, ensure eq. are ref'able (#2636)

Also changes the execution of the lazy auto api generation to only run on demand (in the CI and RTD)

Blocked by:
- #2610

.github/workflows/docs.yml

@@ -49,6 +49,7 @@ jobs:
           -W
           --keep-going
           -t run_doxygen
+          -t lazy_autodoc
           -b linkcheck
           . _build/html/
 

docs/CMakeLists.txt

@@ -14,7 +14,7 @@ list(APPEND sphinx_command "-b;html")
 list(APPEND sphinx_command "-d;${sphinx_doctrees}")
 list(APPEND sphinx_command "-j;auto")
 list(APPEND sphinx_command "-W;--keep-going")
-list(APPEND sphinx_command "-t;run_doxygen")
+list(APPEND sphinx_command "-t;run_doxygen;-t;lazy_autodoc")
 
 if(DEFINED ENV{CI})
   list(APPEND sphinx_command "-b;linkcheck")

docs/_static/custom.css

@@ -1,3 +1,29 @@
 .wy-side-nav-search > a img.logo {
   width: 200px;
 }
+
+.math {
+      text-align: left;
+}
+.eqno {
+      float: right;
+}
+
+.admonition.seealso .admonition-title::before {
+    content: ""; /* font awesome: share */
+}
+
+.admonition.caution .admonition-title::before,
+.admonition.danger .admonition-title::before,
+.admonition.warning .admonition-title::before {
+    content: ""; /* font awesome: triangle-exclamation */
+}
+
+.admonition.error .admonition-title::before {
+  content: ""; /* font awesome: circle-xmark */
+}
+
+.admonition.hint .admonition-title::before,
+.admonition.tip .admonition-title::before {
+  content: ""; /* font awesome: lightbulb */
+}

docs/conf.py

@@ -57,6 +57,7 @@
 
 myst_enable_extensions = ["dollarmath", "colon_fence", "amsmath", "html_image"]
 myst_heading_anchors = 3
+myst_dmath_allow_labels = True
 
 linkcheck_retries = 5
 linkcheck_ignore = [
@@ -161,7 +162,8 @@
     if not api_index_target.exists():
         shutil.copyfile(doc_dir / "api/api_index.rst", api_index_target)
     print("breathe apidoc completed")
-else:
+
+if tags.has("lazy_autodoc") or on_readthedocs:
     extensions += ["lazy_autodoc"]