docs: Add white paper index to the documentation

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/conf.py

@@ -47,7 +47,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

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/index.rst

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

docs/requirements.in

@@ -2,4 +2,4 @@ breathe
 myst-parser
 sphinx
 sphinx_rtd_theme
-docutils<0.17.0 # see https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
+docutils

docs/requirements.txt

@@ -1,85 +1,83 @@
 #
-# 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
 #
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-babel==2.10.3
+babel==2.13.1
     # via sphinx
-breathe==4.34.0
+breathe==4.35.0
     # via -r docs/requirements.in
-certifi==2022.6.15
+certifi==2023.7.22
     # via requests
-charset-normalizer==2.1.0
+charset-normalizer==3.3.1
     # via requests
-docutils==0.16
+docutils==0.18.1
     # via
     #   -r docs/requirements.in
     #   breathe
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.3
+idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==4.12.0
-    # via sphinx
 jinja2==3.1.2
     # via
     #   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
+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
+myst-parser==2.0.0
     # via -r docs/requirements.in
-packaging==21.3
+packaging==23.2
     # via sphinx
-pygments==2.12.0
+pygments==2.16.1
     # via sphinx
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.2.1
-    # via babel
-pyyaml==6.0
+pyyaml==6.0.1
     # via myst-parser
-requests==2.28.1
+requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==5.1.1
+sphinx==7.2.6
     # via
     #   -r docs/requirements.in
     #   breathe
     #   myst-parser
     #   sphinx-rtd-theme
-sphinx-rtd-theme==1.0.0
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-rtd-theme==1.3.0
     # via -r docs/requirements.in
-sphinxcontrib-applehelp==1.0.2
+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
+urllib3==2.0.7
     # via requests
-zipp==3.8.1
-    # via importlib-metadata

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/whitepapers/how-to-add.md

@@ -0,0 +1,194 @@
+# How to add a whitepaper
+
+The whitepaper collection is managed through a configuration file that
+contains information on registered whitepaper. This configuration can be
+automatically updated from GitHub by a script that will pull some meta
+information like the title, authors and abstract. It will also grab the
+most latest compiled PDF from the source repository that was created by a
+CI job.
+
+To get started, head over to the whitepaper template
+[repository](https://github.com/acts-project/whitepaper-template). There
+should be a button toward the top right that says *Use this template*,
+which will allow you to create a copy of the content of the template
+repository into a repository of your own.
+
+:::{tip}
+You can get started by creating a whitepaper repository using the template
+under your own account. However, when the document finalizes, consider
+moving it into the ACTS organization (`acts-project`), which helps
+management of documents.
+:::
+
+The project will immediately start building the basic default note with
+dummy content using GitHub Actions. You can now clone and start making
+changes to the document and compile locally. 
+
+:::{tip}
+:name: latexmk-tip
+The easiest way to compile the document is `latexmk`. Simply unning `latexmk`
+in the root directory will automatically compile the source code the right
+number of times, and also run `biber` that generates the references from the
+example `references.bib` file. You don't have to use `latexmk`, but it's very
+convenient! The output file when using `latexmk` will be in a subfolder `build`
+of the root directory.
+:::
+
+:::{note}
+The note template requires LuaLatex, which should be found in any default
+LaTeX installations. `latexmk` is configured to use LuaLatex by default.
+:::
+
+## Template repository structure
+
+The content of the template repository will look something like this:
+
+```console
+whitepaper-template
+├── main.tex
+├── metadata.tex
+├── abstract.tex
+├── references.bib
+├── latexmkrc
+└── theme
+    ├── acts.sty
+    └── logo_acts.pdf
+```
+
+- `main.tex` is the root source file for the document, and you can edit it to
+changed the content of the document.
+
+- `metadata.tex` and `abstract.tex` contain the document title, authors and
+   abstract. Their content is consumed by the workflow described in
+   [](#whitepaper_index_update).
+
+   `metadata.tex` contains the two standard LaTeX commands:
+
+   ```tex
+   \title{A whitepaper about a topic}
+   \author{First Author \and Second Author}
+   ```
+
+   Note how the `\author` directive is given multiple authors separated by `\and`.
+   The workflow below uses the literal `\and` to separate out different authors.
+
+   `abstract.tex` contains the **content** of the abstract only, and is loaded
+   into the abstract in the `main.tex` document like:
+
+   ```tex
+   \begin{abstract}
+       \input{abstract.tex}
+   \end{abstract}
+   ```
+
+   :::{warning}
+   While LaTeX supports arbitrary content in the abstract, the index that lives in
+   the documentation only supports basic math markup.
+   :::
+
+- `references.bib` contains an example reference in standard *bibtex* format, and
+  is a good place to add any additional references that you want to cite in 
+  your document.
+
+- `latexmkrc` configures `latexmk` (see [here](#latexmk-tip))
+
+- `theme` contains the overall theme of the document. You do not typically need 
+  to change anything in this folder.
+
+## Integrate with Overleaf
+
+[Overleaf](https://overleaf.com) is a convenient web-based LaTeX authoring tool. It has GitHub integration 🎉!
+
+:::{image} ../figures/whitepapers/overleaf_import_github.png
+:align: center
+:::
+
+You can then go to the *Menu* on the top right, and click on *GitHub* in the drawer menu to pull changes from GitHub, and to push changes that you made on Overleaf!
+
+:::{danger}
+Overleaf is not particularly good at handling merge conflicts, so try not to make changes on both GitHub and Overleaf.
+:::
+
+For the document to compile without errors on Overleaf, you will have to change the compiler to LuaLatex, by going to *Menu* in the top right, and changing the *Compiler* setting:
+
+:::{image} ../figures/whitepapers/overleaf_compiler.png
+:align: center
+:::
+
+(whitepaper_index_update)=
+## Update the whitepaper overview
+
+The whitepaper overview in this documentation [here](#whitepaper-index) is
+automatically generated using a registry file and a script, both of which are
+located in the main ACTS repository under `whitepapers`.
+
+The registration file `whitepapers/whitepapers.toml` contains a list of all
+known whitepapers, and also stores metadata information on the whitepaper. It looks something like:
+
+```toml
+[[whitepapers]]
+repository = "https://github.com/acts-project/whitepaper-template"
+
+[whitepapers.metadata]
+authors = [ "First Author", "Second Author",]
+title = "A whitepaper about a topic"
+description = "This is a whitepaper example. It contains a number of example\npatterns, layouts etc.\nSimple math like $a + b = c$ or even $\\sqrt{s} = 14$ TeV is supported!\n\nQuisque ullamcorper placerat ipsum. Cras nibh. Morbi vel justo vitae lacus\ntincidunt ultrices. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. In hac\nhabitasse platea dictumst. Integer tempus convallis augue. Etiam facilisis. Nunc\nelementum fermentum wisi. Aenean placerat. Ut imperdiet, enim sed gravida\nsollicitudin, felis odio placerat quam, ac pulvinar elit purus eget enim. Nunc vitae\ntortor. Proin tempus nibh sit amet nisl. Vivamus quis tortor vitae risus porta\nvehicula."
+```
+
+`[[whitepapers]]` indicates a whitepaper entry, while `[whitepapers.metadata]` is a dictionary containing the metadata for that whitepaper.
+
+:::{note}
+`[whitepapers.metadata]` is auto-generated!
+:::
+
+To add a new whitepaper, simply add a new section at the bottom of the file:
+
+```toml
+[[whitepapers]]
+repository = "https://github.com/acts-project/another-whitepaper"
+slug = "another-whitepaper"
+```
+
+Note that `slug` should be lower case, not contain spaces, and be unique.
+
+The script `whitepapers/update.py` is used to complete the metadata information
+for the whitepapers. To run it, you need to install the dependencies in
+`whitepapers/requirements.txt` using `pip`.
+
+:::{tip}
+It is **strongly recommended** to use a [virtual
+environment](https://realpython.com/python-virtual-environments-a-primer/) for
+this purpose! For example, run 
+
+```console
+$ python -m venv venv
+$ source venv/bin/activate
+```
+
+to create a local virtual environment, and then run the `pip` command above.
+:::
+
+You also need the `convert` executable from
+[ImageMagick](https://imagemagick.org/) available on your `$PATH`.  You can
+then run 
+
+```console
+$ whitepaper/update.py pull
+```
+
+which will for each whitepaper listed in `whitepapers.toml`
+
+1. Download the most recent PDF of the document built by that repository's CI
+2. Make a PNG of the first page of that PDF to be displayed in the documentation
+3. Download `metadata.tex` and `abstract.tex` from the repository, and parse 
+   them to extract the title, authors and abstract content.
+
+Afterwards, the `whitepapers.toml` should now contain updated information
+from all listed whitepapers. Another command can be used to actually create
+the listing in the documentation 
+
+```console
+$ whitepaper/update.py render
+```
+
+This will use the `whitepapers.toml` file to generate a markdown file at `docs/whitepapers/whitepapers.md`, that is then used by the regular documentation build, which you can read more about [here](#build_docs).

docs/whitepapers/index.md

@@ -0,0 +1,22 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% THIS FILE IS AUTOGENERATED, DO NOT MANUALLY MODIFY IT!
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+(whitepaper-index)=
+# Whitepapers
+
+This is a collection of whitepapers documenting methods and approaches used
+in ACTS.
+
+:::{toctree}
+:maxdepth: 1
+
+how-to-add
+
+
+
+whitepaper-template
+
+
+
+:::