acts/docs/conf.py

0001 # Configuration file for the Sphinx documentation builder.
0002
0003 import os
0004 import sys
0005 import subprocess
0006 from pathlib import Path
0007 import shutil
0008 import datetime
0009
0010 # check if we are running on readthedocs.org
0011 on_readthedocs = os.environ.get("READTHEDOCS", None) == "True"
0012
0013 # -- Project information ------------------------------------------------------
0014
0015 project = "Acts"
0016 author = "The Acts authors"
0017 copyright = (
0018     f"2014–{datetime.date.today().year} CERN for the benefit of the Acts project"
0019 )
0020 # version = '@PROJECT_VERSION@'
0021 # release = '@PROJECT_VERSION@'
0022
0023 # -- General ------------------------------------------------------------------
0024
0025 doc_dir = Path(__file__).parent
0026
0027 sys.path.insert(0, str(doc_dir))
0028 sys.path.insert(0, str(doc_dir / "_extensions"))
0029
0030 extensions = [
0031     "breathe",
0032     "myst_parser",
0033     "sphinx.ext.mathjax",
0034     "sphinx.ext.graphviz",
0035     "sphinx.ext.todo",
0036     "warnings_filter",
0037 ]
0038
0039 todo_include_todos = True
0040
0041 warnings_filter_config = str(doc_dir / "known-warnings.txt")
0042 warnings_filter_silent = True
0043
0044 source_suffix = {
0045     ".rst": "restructuredtext",
0046     ".md": "markdown",
0047 }
0048 master_doc = "index"
0049 # ensure the in-source build directory is ignored
0050 exclude_patterns = ["_build", "api/api_stub.rst", "api/api_index.rst"]
0051 # cpp as default language
0052 primary_domain = "cpp"
0053 highlight_language = "cpp"
0054 smartquotes = True
0055 numfig = True
0056
0057 myst_enable_extensions = ["dollarmath", "colon_fence", "amsmath", "html_image"]
0058 myst_heading_anchors = 3
0059 myst_dmath_allow_labels = True
0060
0061 linkcheck_retries = 5
0062 linkcheck_ignore = [
0063     r"https://doi.org/.*",
0064     r"https://cernvm.cern.ch/.*",
0065     r"http://eigen.tuxfamily.org.*",
0066     r"https://pythia.org.*",
0067     r"https://lcginfo.cern.ch/.*",
0068     r"https://.*\.?intel.com/.*",
0069     r"https://www.conventionalcommits.org/.*",
0070     r"https://cds.cern.ch/record/.*",
0071 ]
0072
0073 # -- Options for HTML output --------------------------------------------------
0074
0075 html_theme = "sphinx_rtd_theme"
0076 extensions.append("sphinx_rtd_theme")
0077
0078 html_theme_options = {
0079     "collapse_navigation": False,
0080     "navigation_depth": 4,
0081     "prev_next_buttons_location": None,  # no prev/next links
0082     "style_external_links": True,
0083 }
0084 html_logo = "figures/acts_logo_white.svg"
0085 html_static_path = [
0086     "_static",
0087 ]
0088 html_css_files = [
0089     "custom.css",
0090 ]
0091 html_copy_source = False
0092 html_show_sourcelink = False
0093 html_show_sphinx = False
0094
0095 # -- Doxygen integration with Breathe -----------------------------------------
0096
0097 breathe_projects = {
0098     "Acts": "_build/doxygen-xml",
0099 }
0100 breathe_default_project = "Acts"
0101 breathe_domain_by_extension = {
0102     "cpp": "cpp",
0103     "hpp": "cpp",
0104     "ipp": "cpp",
0105 }
0106 breathe_default_members = (
0107     "members",
0108     "undoc-members",
0109 )
0110
0111 nitpicky = True
0112 nitpick_ignore = [
0113     ("cpp:identifier", "Acts"),
0114     ("cpp:identifier", "detail"),
0115     ("cpp:identifier", "SIZE_MAX"),
0116     ("cpp:identifier", "M_PI"),
0117     ("cpp:identifier", "eSize"),
0118     ("cpp:identifier", "eBoundSize"),
0119     ("cpp:identifier", "eFreeSize"),
0120     ("cpp:identifier", "open"),
0121     ("cpp:identifier", "FreeToBoundCorrection"),
0122 ]
0123
0124 nitpick_ignore_regex = [
0125     ("cpp:identifier", r"Eigen.*"),
0126     ("cpp:identifier", r"boost.*"),
0127     ("cpp:identifier", r"s_.*"),
0128     ("cpp:identifier", r"detail::.*"),
0129     ("cpp:identifier", ".*::Identity"),
0130     ("cpp:identifier", ".*::Zero"),
0131     # This blanket ignore only targets the doxygen/breathe auto-generated
0132     # references. Explicit references should have specific types.
0133     ("cpp:identifier", r".*"),
0134 ]
0135
0136 # -- Automatic API documentation ---------------------------------------------
0137
0138 env = os.environ.copy()
0139
0140 if on_readthedocs or tags.has("run_doxygen"):
0141     # if we are running on RTD Doxygen must be run as part of the build
0142     print("Executing doxygen in", doc_dir)
0143     print(
0144         "Doxygen version:",
0145         subprocess.check_output(["doxygen", "--version"], encoding="utf-8"),
0146     )
0147     sys.stdout.flush()
0148     subprocess.check_call(
0149         ["doxygen", "Doxyfile"], stdout=subprocess.PIPE, cwd=doc_dir, env=env
0150     )
0151
0152 api_index_target = doc_dir / "api/api.md"
0153
0154 if tags.has("run_apidoc"):
0155     print("Executing breathe apidoc in", doc_dir)
0156     subprocess.check_call(
0157         [sys.executable, "-m", "breathe.apidoc", "_build/doxygen-xml", "-o", "api"],
0158         stdout=subprocess.DEVNULL,
0159         cwd=doc_dir,
0160         env=env,
0161     )
0162     if not api_index_target.exists():
0163         shutil.copyfile(doc_dir / "api/api_index.rst", api_index_target)
0164     print("breathe apidoc completed")
0165
0166 if tags.has("lazy_autodoc") or on_readthedocs:
0167     extensions += ["lazy_autodoc"]
0168
0169
0170 if on_readthedocs or tags.has("white_papers"):
0171     import white_papers
0172
0173     white_papers.render()
0174
0175 # -- Markdown bridge setup hook (must come last, not sure why) ----------------
0176
0177
0178 def setup(app):
0179     pass