updates for optical docs

docs/source/conf.py

@@ -4,7 +4,10 @@
 import importlib.metadata
 import sys
 from pathlib import Path
+from typing import ClassVar
 
+from pygments.lexer import RegexLexer
+from pygments.token import Comment, Name, Text
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 
 sys.path.insert(0, Path(__file__).parents[2].resolve().as_posix())
@@ -79,3 +82,33 @@
     "ArrayLike": "ArrayLike",
     "NDArray": "NDArray",
 }
+
+
+def _replace(app, docname, source):  # noqa: ARG001
+    result = source[0]
+    for key in app.config.ultimate_replacements:
+        result = result.replace(key, app.config.ultimate_replacements[key])
+    source[0] = result
+
+
+class Geant4MacroLexer(RegexLexer):
+    name: str = "Geant4Macro"
+    aliases: ClassVar[list[str]] = ["geant4", "g4mac"]
+    filenames: ClassVar[list[str]] = ["*.mac"]
+
+    tokens: ClassVar[dict] = {
+        "root": [
+            # comments
+            (r"#.*$", Comment),
+            # command name at start of line
+            (r"^(/\S+)", Name.Function),
+            # geant4 alias
+            (r"\{\w+\}", Name.Variable),
+            # any other text
+            (r".", Text),
+        ],
+    }
+
+
+def setup(app):
+    app.add_lexer("geant4", Geant4MacroLexer)

docs/source/manual/optical.md

@@ -2,20 +2,14 @@
 
 # Using optical maps
 
-:::{warning}
-
-Work in progress, more will be added later!
-
-:::
-
 ## Creating optical maps
 
 ### 1. Running remage simulations to get an stp file
 
 The map generation is performed directly with _remage_ (_reboost_ is not involved
 in this step). An example macro to showcase the required settings (`map.mac`):
 
-```
+```geant4
 /RMG/Processes/OpticalPhysics true
 /RMG/Processes/OpticalPhysicsMaxOneWLSPhoton true
 
@@ -36,7 +30,7 @@ in this step). An example macro to showcase the required settings (`map.mac`):
 /RMG/Generator/Confinement/SamplingMode IntersectPhysicalWithGeometrical
 /RMG/Generator/Confinement/ForceContainmentCheck true
 
-/RMG/Generator/Confinement/Physical/AddVolume lar
+/RMG/Generator/Confinement/Physical/AddVolume liquid_argon
 
 /RMG/Generator/Confinement/Geometrical/AddSolid Cylinder
 /RMG/Generator/Confinement/Geometrical/CenterPositionX 0 m
@@ -58,6 +52,14 @@ in this step). An example macro to showcase the required settings (`map.mac`):
 /run/beamOn 80000000
 ```
 
+:::{important}
+
+This macro assumes the most recent versions of _remage_ (0.18+) and
+_legend-pygeom-l200_ (0.7.0+) are being used. In older versions, not all macro
+commands might be available or volumes might be named differently.
+
+:::
+
 Run remage with this macro to produce the (flat) output file:
 
 ```
@@ -76,7 +78,7 @@ range_in_m:
 bins: [280, 280, 480]
 ```
 
-```
+```console
 $ reboost-optical createmap --settings map-settings.yaml --geom l200-geometry.gdml map.stp.lh5 map.map.lh5
 ```
 
@@ -109,7 +111,7 @@ of 4096 remage output files can be read in parallel.
 
 The 12-16 output files can then be combined into one with
 
-```
+```console
 $ reboost-optical mergemap --settings map-settings.yaml map.map*.lh5 final-output-map.lh5
 ```