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::ActsScalar",
0044         "Acts::ActsVector",
0045         "Acts::ActsMatrix",
0046         "Acts::ActsSquareMatrix",
0047         "Acts::SquareMatrix2",
0048         "Acts::SquareMatrix3",
0049         "Acts::SquareMatrix4",
0050         "Acts::BoundMatrix",
0051         "Acts::BoundSquareMatrix",
0052         "Acts::Vector2",
0053         "Acts::Vector3",
0054         "Acts::Vector4",
0055         "Acts::BoundVector",
0056         "Acts::BoundTrackParameters",
0057         "Acts::Transform2",
0058         "Acts::Transform3",
0059         "Acts::AngleAxis3",
0060         "Acts::RotationMatrix2",
0061         "Acts::RotationMatrix3",
0062         "Acts::Translation2",
0063         "Acts::Translation3",
0064         "Acts::GeometryContext",
0065         "Acts::FreeVector",
0066         "Acts::FreeMatrix",
0067         "Acts::SurfaceVector",
0068         "Acts::Intersection3D",
0069         "Acts::BoundToFreeMatrix",
0070         "Acts::FreeToBoundMatrix",
0071         "Acts::FreeSquareMatrix",
0072         "Acts::FreeToPathMatrix",
0073         "Acts::HashedString",
0074     }
0075
0076     role_instances["struct"] |= {
0077         "Acts::DenseStepperPropagatorOptions",
0078         "Acts::Experimental::DetectorNavigator::State",
0079         "Acts::Geant4PhysicalVolumeSelectors::AllSelector",
0080         "Acts::Geant4PhysicalVolumeSelectors::NameSelector",
0081         "Acts::Geant4PhysicalVolumeSelectors::PositionSelector",
0082         "Acts::OrientedSurface",
0083     }
0084
0085     role_instances["class"] |= {
0086         "Acts::BinningData",
0087         "Acts::Direction",
0088         "Acts::ConstrainedStep",
0089         "Acts::IAxis",
0090         "Acts::SeedFilter",
0091         "Acts::BoundaryCheck",
0092         "Acts::ConeVolumeBounds",
0093         "Acts::CuboidVolumeBounds",
0094         "Acts::CylinderVolumeBounds",
0095         "Acts::CutoutCylinderVolumeBounds",
0096         "Acts::GenericCuboidVolumeBounds",
0097         "Acts::TrapezoidVolumeBounds",
0098         "Acts::GeometryObject",
0099         "Acts::TrackContainer",
0100         "Acts::ConeLayer",
0101         "Acts::CylinderLayer",
0102         "Acts::IdentifiedDetectorElement",
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::Measurement",
0120         "Acts::SourceLink",
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::BinningValue",
0135         "Acts::BinningType",
0136         "Acts::BinningValue",
0137         "Acts::BoundIndices",
0138         "Acts::FreeIndices",
0139         "Acts::MagneticFieldError",
0140         "Acts::TrackStatePropMask",
0141     }
0142
0143     role_ex = re.compile(r"[{:](" + "|".join(roles) + r")[}:]`(.+?)`")
0144
0145     def process_roles(file: Path) -> List[Tuple[str, str]]:
0146         text = file.read_text()
0147         return [m.groups() for m in role_ex.finditer(text)]
0148
0149     for dirpath, _, filenames in os.walk(doc_dir):
0150         dirpath = Path(dirpath)
0151         for file in filenames:
0152             file = dirpath / file
0153             if file.suffix not in (".rst", ".md"):
0154                 continue
0155             for role, arg in process_roles(file):
0156                 role_instances[role].add(arg)
0157
0158     # add members to their parents
0159
0160     api_preamble = """
0161 """
0162
0163     with api_index_target.open("w") as fh:
0164         fh.write("# API Reference\n\n")
0165         fh.write(api_preamble)
0166         for role, instances in sorted(role_instances.items(), key=lambda x: x[0]):
0167             fh.write(f"## {role_names[role]}\n")
0168             for instance in sorted(instances):
0169                 fh.write(
0170                     f"""
0171 :::{{{directives[role]}}} {instance}
0172 :::
0173 """
0174                 )
0175             fh.write("\n")
0176
0177
0178 def setup(app: Sphinx) -> Dict[str, Any]:
0179     run()
0180
0181     return {
0182         "version": __version__,
0183         "parallel_read_safe": True,
0184         "parallel_write_safe": True,
0185     }