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