docs/_extensions/lazy_autodoc.py

0001 import re
0002 from typing import Dict, Any, List, Tuple
0003 from pathlib import Path
0004 import os
0005
0006 from sphinx.application import Sphinx
0007
0008
0009 __version__ = "0.1.0"
0010
0011
0012 def run() -> None:
0013     doc_dir = Path(__file__).parent.parent
0014     api_index_target = doc_dir / "api/api.md"
0015
0016     roles = [
0017         "class",
0018         "struct",
0019         "type",
0020         #  "func",
0021         "enum",
0022     ]
0023
0024     role_names = {
0025         "class": "Classes",
0026         "struct": "Structs",
0027         "type": "Types",
0028         "enum": "Enums",
0029         "func": "Functions",
0030     }
0031
0032     directives = {
0033         "class": "doxygenclass",
0034         "struct": "doxygenstruct",
0035         "type": "doxygentypedef",
0036         "func": "doxygenfunction",
0037         "enum": "doxygenenum",
0038     }
0039
0040     role_instances = {k: set() for k in roles}
0041
0042     role_instances["type"] |= {
0043         "Acts::ActsVector",
0044         "Acts::ActsMatrix",
0045         "Acts::ActsSquareMatrix",
0046         "Acts::SquareMatrix2",
0047         "Acts::SquareMatrix3",
0048         "Acts::SquareMatrix4",
0049         "Acts::BoundMatrix",
0050         "Acts::BoundSquareMatrix",
0051         "Acts::Vector2",
0052         "Acts::Vector3",
0053         "Acts::Vector4",
0054         "Acts::BoundVector",
0055         "Acts::BoundTrackParameters",
0056         "Acts::Transform2",
0057         "Acts::Transform3",
0058         "Acts::AngleAxis3",
0059         "Acts::RotationMatrix2",
0060         "Acts::RotationMatrix3",
0061         "Acts::Translation2",
0062         "Acts::Translation3",
0063         "Acts::FreeVector",
0064         "Acts::FreeMatrix",
0065         "Acts::SurfaceVector",
0066         "Acts::Intersection3D",
0067         "Acts::BoundToFreeMatrix",
0068         "Acts::FreeToBoundMatrix",
0069         "Acts::FreeSquareMatrix",
0070         "Acts::FreeToPathMatrix",
0071         "Acts::HashedString",
0072     }
0073
0074     role_instances["struct"] |= {
0075         "Acts::Geant4PhysicalVolumeSelectors::AllSelector",
0076         "Acts::Geant4PhysicalVolumeSelectors::NameSelector",
0077         "Acts::Geant4PhysicalVolumeSelectors::PositionSelector",
0078         "Acts::OrientedSurface",
0079         "Acts::TrackStateCreator",
0080     }
0081
0082     role_instances["class"] |= {
0083         "Acts::GeometryContext",
0084         "Acts::MagneticFieldContext",
0085         "Acts::CalibrationContext",
0086         "Acts::BinningData",
0087         "Acts::Direction",
0088         "Acts::ConstrainedStep",
0089         "Acts::Axis",
0090         "Acts::IAxis",
0091         "Acts::SeedFilter",
0092         "Acts::BoundaryTolerance",
0093         "Acts::ConeVolumeBounds",
0094         "Acts::CuboidVolumeBounds",
0095         "Acts::CylinderVolumeBounds",
0096         "Acts::CutoutCylinderVolumeBounds",
0097         "Acts::GenericCuboidVolumeBounds",
0098         "Acts::TrapezoidVolumeBounds",
0099         "Acts::CylinderVolumeStack",
0100         "Acts::CuboidVolumeStack",
0101         "Acts::VolumeStack",
0102         "Acts::GeometryObject",
0103         "Acts::TrackContainer",
0104         "Acts::ConeLayer",
0105         "Acts::CylinderLayer",
0106         "Acts::DiscLayer",
0107         "Acts::PlaneLayer",
0108         "Acts::NullBField",
0109         "Acts::DiscBounds",
0110         "Acts::PlanarBounds",
0111         "Acts::AnnulusBounds",
0112         "Acts::DiamondBounds",
0113         "Acts::RegularSurface",
0114         "Acts::ConvexPolygonBounds",
0115         "Acts::ConvexPolygonBoundsBase",
0116         "Acts::Logging::LevelOutputDecorator",
0117         "Acts::Logging::NamedOutputDecorator",
0118         "Acts::Logging::ThreadOutputDecorator",
0119         "Acts::Logging::TimedOutputDecorator",
0120         "Acts::Logging::DefaultFilterPolicy",
0121         "Acts::Logging::DefaultPrintPolicy",
0122         "Acts::SourceLink",
0123         "Acts::JsonDetectorElement",
0124     }
0125
0126     role_instances["func"] = {
0127         "Acts::CylinderVolumeBuilder::logger",
0128         "Acts::getDefaultLogger",
0129         "Acts::getDummyLogger",
0130         "Acts::makeDefaultBetheHeitlerApprox",
0131         "Acts::reduceMixtureLargestWeights",
0132         "Acts::reduceMixtureWithKLDistance",
0133         "Acts::convertDD4hepDetector",
0134     }
0135
0136     role_instances["enum"] = {
0137         "Acts::AxisDirection",
0138         "Acts::BinningType",
0139         "Acts::BoundIndices",
0140         "Acts::FreeIndices",
0141         "Acts::MagneticFieldError",
0142         "Acts::TrackStatePropMask",
0143         "Acts::AxisType",
0144         "Acts::AxisBoundaryType",
0145     }
0146
0147     role_ex = re.compile(r"[{:](" + "|".join(roles) + r")[}:]`(.+?)`")
0148
0149     def process_roles(file: Path) -> List[Tuple[str, str]]:
0150         text = file.read_text()
0151         return [m.groups() for m in role_ex.finditer(text)]
0152
0153     for dirpath, _, filenames in os.walk(doc_dir):
0154         dirpath = Path(dirpath)
0155         for file in filenames:
0156             file = dirpath / file
0157             if file.suffix not in (".rst", ".md"):
0158                 continue
0159             for role, arg in process_roles(file):
0160                 role_instances[role].add(arg)
0161
0162     # add members to their parents
0163
0164     api_preamble = """
0165 """
0166
0167     with api_index_target.open("w") as fh:
0168         fh.write("# API Reference\n\n")
0169         fh.write(api_preamble)
0170         for role, instances in sorted(role_instances.items(), key=lambda x: x[0]):
0171             fh.write(f"## {role_names[role]}\n")
0172             for instance in sorted(instances):
0173                 fh.write(
0174                     f"""
0175 :::{{{directives[role]}}} {instance}
0176 :::
0177 """
0178                 )
0179             fh.write("\n")
0180
0181
0182 def setup(app: Sphinx) -> Dict[str, Any]:
0183     run()
0184
0185     return {
0186         "version": __version__,
0187         "parallel_read_safe": True,
0188         "parallel_write_safe": True,
0189     }