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     }
0080
0081     role_instances["class"] |= {
0082         "Acts::GeometryContext",
0083         "Acts::MagneticFieldContext",
0084         "Acts::CalibrationContext",
0085         "Acts::BinningData",
0086         "Acts::Direction",
0087         "Acts::ConstrainedStep",
0088         "Acts::Axis",
0089         "Acts::IAxis",
0090         "Acts::SeedFilter",
0091         "Acts::BoundaryTolerance",
0092         "Acts::ConeVolumeBounds",
0093         "Acts::CuboidVolumeBounds",
0094         "Acts::CylinderVolumeBounds",
0095         "Acts::CutoutCylinderVolumeBounds",
0096         "Acts::GenericCuboidVolumeBounds",
0097         "Acts::TrapezoidVolumeBounds",
0098         "Acts::CylinderVolumeStack",
0099         "Acts::GeometryObject",
0100         "Acts::TrackContainer",
0101         "Acts::ConeLayer",
0102         "Acts::CylinderLayer",
0103         "Acts::DiscLayer",
0104         "Acts::PlaneLayer",
0105         "Acts::NullBField",
0106         "Acts::DiscBounds",
0107         "Acts::PlanarBounds",
0108         "Acts::AnnulusBounds",
0109         "Acts::DiamondBounds",
0110         "Acts::RegularSurface",
0111         "Acts::ConvexPolygonBounds",
0112         "Acts::ConvexPolygonBoundsBase",
0113         "Acts::Logging::LevelOutputDecorator",
0114         "Acts::Logging::NamedOutputDecorator",
0115         "Acts::Logging::ThreadOutputDecorator",
0116         "Acts::Logging::TimedOutputDecorator",
0117         "Acts::Logging::DefaultFilterPolicy",
0118         "Acts::Logging::DefaultPrintPolicy",
0119         "Acts::SourceLink",
0120         "Acts::JsonDetectorElement",
0121     }
0122
0123     role_instances["func"] = {
0124         "Acts::CylinderVolumeBuilder::logger",
0125         "Acts::getDefaultLogger",
0126         "Acts::getDummyLogger",
0127         "Acts::makeDefaultBetheHeitlerApprox",
0128         "Acts::reduceMixtureLargestWeights",
0129         "Acts::reduceMixtureWithKLDistance",
0130         "Acts::convertDD4hepDetector",
0131     }
0132
0133     role_instances["enum"] = {
0134         "Acts::AxisDirection",
0135         "Acts::BinningType",
0136         "Acts::BoundIndices",
0137         "Acts::FreeIndices",
0138         "Acts::MagneticFieldError",
0139         "Acts::TrackStatePropMask",
0140         "Acts::AxisType",
0141         "Acts::AxisBoundaryType",
0142     }
0143
0144     role_ex = re.compile(r"[{:](" + "|".join(roles) + r")[}:]`(.+?)`")
0145
0146     def process_roles(file: Path) -> List[Tuple[str, str]]:
0147         text = file.read_text()
0148         return [m.groups() for m in role_ex.finditer(text)]
0149
0150     for dirpath, _, filenames in os.walk(doc_dir):
0151         dirpath = Path(dirpath)
0152         for file in filenames:
0153             file = dirpath / file
0154             if file.suffix not in (".rst", ".md"):
0155                 continue
0156             for role, arg in process_roles(file):
0157                 role_instances[role].add(arg)
0158
0159     # add members to their parents
0160
0161     api_preamble = """
0162 """
0163
0164     with api_index_target.open("w") as fh:
0165         fh.write("# API Reference\n\n")
0166         fh.write(api_preamble)
0167         for role, instances in sorted(role_instances.items(), key=lambda x: x[0]):
0168             fh.write(f"## {role_names[role]}\n")
0169             for instance in sorted(instances):
0170                 fh.write(
0171                     f"""
0172 :::{{{directives[role]}}} {instance}
0173 :::
0174 """
0175                 )
0176             fh.write("\n")
0177
0178
0179 def setup(app: Sphinx) -> Dict[str, Any]:
0180     run()
0181
0182     return {
0183         "version": __version__,
0184         "parallel_read_safe": True,
0185         "parallel_write_safe": True,
0186     }