docs: Add white paper index to the documentation (#2591)

CI/release.py

@@ -371,7 +371,6 @@ async def pr_action(
     token: Optional[str] = typer.Option(None, envvar="GH_TOKEN"),
     repo: Optional[str] = typer.Option(None, envvar="GH_REPO"),
 ):
-
     print("::group::Information")
 
     context = os.environ.get("GITHUB_CONTEXT")
@@ -437,7 +436,6 @@ async def pr_action(
         exit_code = 0
 
         if existing_release is not None or existing_tag is not None:
-
             if current_version == next_version:
                 body += (
                     "## :no_entry_sign: Merging this will not result in a new version (no `fix`, "

docs/.gitignore

@@ -2,3 +2,5 @@
 _build/
 # auto-generated api documentation
 api/
+white_papers/*.md
+!white_papers/how_to_add.md

docs/conf.py

@@ -22,6 +22,7 @@
 
 # -- General ------------------------------------------------------------------
 
+sys.path.insert(0, str(Path(__file__).parent))
 sys.path.insert(0, str(Path(__file__).parent / "_extensions"))
 
 extensions = [
@@ -47,7 +48,7 @@
 smartquotes = True
 numfig = True
 
-myst_enable_extensions = ["dollarmath", "colon_fence", "amsmath"]
+myst_enable_extensions = ["dollarmath", "colon_fence", "amsmath", "html_image"]
 myst_heading_anchors = 3
 
 linkcheck_retries = 5
@@ -133,6 +134,10 @@
     if not api_index_target.exists():
         shutil.copyfile(cwd / "api/api_stub.rst", api_index_target)
 
+import white_papers
+
+white_papers.render()
+
 # -- Markdown bridge setup hook (must come last, not sure why) ----------------
 
 

docs/examples/python_bindings.rst

@@ -94,6 +94,7 @@ Examples/Python/tests/requirements.txt`` from the repository root.  You can
 then simply run ``pytest`` from the repository root.
 
 .. tip::
+   :name: python-virtualenv
 
    It is **strongly recommended** to use a `virtual environment`_ for
    this purpose! For example, run 

docs/getting_started.md

@@ -52,7 +52,7 @@ These are usually not available through the system package manager and can be fo
 
 All external dependencies must be provided prior to building Acts. Compatible
 versions of all dependencies are provided e.g. by the [LCG
-releases](http://lcginfo.cern.ch/) starting from [LCG 97apython3](http://lcginfo.cern.ch/release/97apython3/).
+releases](https://lcginfo.cern.ch/) starting from [LCG 97apython3](https://lcginfo.cern.ch/release/97apython3/).
 For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see [Build options](#build-options).
 Other options are also
 available and are discussed in the [Building Acts](#building-acts) section.

docs/index.rst

@@ -39,3 +39,6 @@ Key features:
    codeguide
    authors
    license
+
+   white_papers/index.rst
+

docs/requirements.in

@@ -2,4 +2,13 @@ breathe
 myst-parser
 sphinx
 sphinx_rtd_theme
-docutils<0.17.0 # see https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
+docutils
+rich
+toml
+typer
+pydantic
+jinja2
+gidgethub
+aiohttp
+python-dotenv
+fsspec

docs/requirements.txt

@@ -1,85 +1,144 @@
 #
-# This file is autogenerated by pip-compile with python 3.9
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
 #
-#    pip-compile docs/requirements.in
+#    pip-compile requirements.in
 #
-alabaster==0.7.12
+aiohttp==3.8.6
+    # via -r requirements.in
+aiosignal==1.3.1
+    # via aiohttp
+alabaster==0.7.13
     # via sphinx
-babel==2.10.3
+annotated-types==0.6.0
+    # via pydantic
+async-timeout==4.0.3
+    # via aiohttp
+attrs==23.1.0
+    # via aiohttp
+babel==2.13.1
     # via sphinx
-breathe==4.34.0
-    # via -r docs/requirements.in
-certifi==2022.6.15
+breathe==4.35.0
+    # via -r requirements.in
+certifi==2023.7.22
     # via requests
-charset-normalizer==2.1.0
-    # via requests
-docutils==0.16
+cffi==1.16.0
+    # via cryptography
+charset-normalizer==3.3.1
+    # via
+    #   aiohttp
+    #   requests
+click==8.1.7
+    # via typer
+cryptography==41.0.5
+    # via pyjwt
+docutils==0.18.1
     # via
-    #   -r docs/requirements.in
+    #   -r requirements.in
     #   breathe
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.3
-    # via requests
+frozenlist==1.4.0
+    # via
+    #   aiohttp
+    #   aiosignal
+fsspec==2023.10.0
+    # via -r requirements.in
+gidgethub==5.3.0
+    # via -r requirements.in
+idna==3.4
+    # via
+    #   requests
+    #   yarl
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==4.12.0
-    # via sphinx
 jinja2==3.1.2
     # via
+    #   -r requirements.in
     #   myst-parser
     #   sphinx
-markdown-it-py==2.1.0
+markdown-it-py==3.0.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==2.1.1
+    #   rich
+markupsafe==2.1.3
     # via jinja2
-mdit-py-plugins==0.3.0
+mdit-py-plugins==0.4.0
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-myst-parser==0.18.0
-    # via -r docs/requirements.in
-packaging==21.3
-    # via sphinx
-pygments==2.12.0
+multidict==6.0.4
+    # via
+    #   aiohttp
+    #   yarl
+myst-parser==2.0.0
+    # via -r requirements.in
+packaging==23.2
     # via sphinx
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.2.1
-    # via babel
-pyyaml==6.0
+pycparser==2.21
+    # via cffi
+pydantic==2.4.2
+    # via -r requirements.in
+pydantic-core==2.10.1
+    # via pydantic
+pygments==2.16.1
+    # via
+    #   rich
+    #   sphinx
+pyjwt[crypto]==2.8.0
+    # via gidgethub
+python-dotenv==1.0.0
+    # via -r requirements.in
+pyyaml==6.0.1
     # via myst-parser
-requests==2.28.1
+requests==2.31.0
     # via sphinx
+rich==13.6.0
+    # via -r requirements.in
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==5.1.1
+sphinx==7.2.6
     # via
-    #   -r docs/requirements.in
+    #   -r requirements.in
     #   breathe
     #   myst-parser
     #   sphinx-rtd-theme
-sphinx-rtd-theme==1.0.0
-    # via -r docs/requirements.in
-sphinxcontrib-applehelp==1.0.2
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-rtd-theme==1.3.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.5
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-htmlhelp==2.0.4
     # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.6
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
-typing-extensions==4.3.0
-    # via myst-parser
-urllib3==1.26.11
+toml==0.10.2
+    # via -r requirements.in
+typer==0.9.0
+    # via -r requirements.in
+typing-extensions==4.8.0
+    # via
+    #   pydantic
+    #   pydantic-core
+    #   typer
+uritemplate==4.1.1
+    # via gidgethub
+urllib3==2.0.7
     # via requests
-zipp==3.8.1
-    # via importlib-metadata
+yarl==1.9.2
+    # via aiohttp

docs/tracking.md

@@ -130,7 +130,7 @@ called *particle propagation* or *extrapolation*, is used to predict a
 particle's properties after it has travelled a certain distance. In many cases,
 the projected intersection with various types of surfaces is desired. The
 trajectory of a charged particle is governed by the [magnetic
-field](core/magnetic_field.rst) through which it travels, as well as any
+field](core/magnetic_field.md) through which it travels, as well as any
 [material effects](core/material.rst). In case of a homogeneous magnetic field,
 and in the absence of material interaction, the particle follows a helical
 trajectory. Such a helix can be calculated purely analytically, although

docs/white_paper_index_template.md.j2

@@ -0,0 +1,23 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% THIS FILE IS AUTOGENERATED, DO NOT MANUALLY MODIFY IT!
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+(white-paper-index)=
+# White papers
+
+This is a collection of white papers documenting methods and approaches used
+in ACTS.
+
+:::{toctree}
+:maxdepth: 1
+
+how_to_add
+
+{% for whp in config.white_papers %}
+
+{{ whp.slug }}
+
+{% endfor %}
+
+:::
+

docs/white_paper_template.md.j2

@@ -0,0 +1,27 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% THIS FILE IS AUTOGENERATED, DO NOT MANUALLY MODIFY IT!
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+({{ whp.slug }})=
+# {{ whp.metadata.title }} 
+[GitHub]({{ whp.repository }})
+{%- if whp.pdf_url is not none %}
+, [PDF]({{ whp.pdf_url }})
+{% endif %}
+
+:::{image} {{ image_path }}/{{ whp.slug }}.png
+:width: 200px
+:align: right
+:::
+
+## Authors
+{% for author in whp.metadata.authors %}
+- {{ author }}
+{% endfor %}
+
+
+## Description
+{{ whp.metadata.description }}
+
+<span style="display:block;clear:both;"></span>
+