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