Merge branch 'upgrade-sphinx-to-v5' into 'master'

Install the third-party dependencies using a package manager.

**Note:** If you have [Anaconda][Anaconda] installed, you already have a working Python installation on your system, and you can omit installing the `python` packages below.

However, notice that there might be issues during [the configuration step](#4-configure-and-build).

However, notice that there might be issues during [the configuration step](#3-configure-and-build).

Have a look at the [troubleshooting](#troubleshooting) section to see how to address them.

##### On Ubuntu (22.04)

        apt update && apt install libtbb-dev

        ```

        Alternatively, one may install the Intel oneAPI base toolkit following these [installation instructions](https://www.intel.com/content/www/us/en/develop/documentation/installation-guide-for-intel-oneapi-toolkits-linux/top/installation/install-using-package-managers/apt.html).

        Alternatively, one may install the Intel oneAPI base toolkit following these [installation instructions](https://www.intel.com/content/www/us/en/docs/oneapi/installation-guide-linux/2024-0/overview.html).

        The only required package is `intel-basekit`.

        It includes the oneDPL library we use for parallelization.

| [pytest](https://docs.pytest.org/)    |          | For model tests |

| [pre-commit](https://pre-commit.com)  | >= 2.18  | For pre-commit hooks |

| [black](https://github.com/psf/black) | >= 22.6  | For formatting python code |

| [Sphinx](https://www.sphinx-doc.org/) | == 4.5.* | Builds the Utopia documentation |

| [Sphinx](https://www.sphinx-doc.org/) | == 5.*   | Builds the Utopia documentation |

These requirements are defined in the `.utopia-env-requirements.txt` file; in case installation fails, a warning will be emitted during [configuration](#3-configure-and-build).

2021

^^^^

With the sunset of the TS-CCEES research group, the Utopia framework has to find a new home ...

The `Utopia Project webpage <https://utopia-project.org>`_ is published.

Code repositories are migrated to a `GitLab.com group <https://gitlab.com/utopia-project>`_.

With the sunset of the TS-CCEES research group, the Utopia framework has to find a new home ...

Benjamin Herdeanu and Yunus Sevinchan defend their doctoral theses; both have been using Utopia extensively.

2022

The `outsourcing of the Utopia frontend <https://gitlab.com/utopia-project/utopia/-/merge_requests/277>`_ brings about a larger architectural change.

This makes the features of `utopya <https://gitlab.com/utopia-project/utopya>`_ available for use with other simulation backends, adds a bunch of new features, expands the documentation, and aims to reduce future maintenance load.

2023

^^^^

Harald Mack and Julian Weninger defend their doctoral theses, using Utopia as the foundation for their computer models.

Utopia is used in `several scientific publications <https://utopia-project.org/publications/>`_.

With utopya as a standalone package, first Python-based models or analysis frameworks are implemented.

# -- General configuration ----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

needs_sphinx = "4.5"

needs_sphinx = "5.3"

# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.

#

# This is also used if you do content translation via gettext catalogs.

# Usually you set "language" from the command line for these cases.

language = None

language = "en"

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

pygments_style = None

# Can suppress some warnings that cannot be resolved

suppress_warnings = []

suppress_warnings = [

    "myst.xref_missing",  # because of different syntax in copied .md files

]

# -- Options for HTML output --------------------------------------------------

# -- MyST ---------------------------------------------------------------------

# Generate heading anchors, which we need for cross-referencing

myst_heading_anchors = 5

# -- Todo extension -----------------------------------------------------------

    r".*COPYING\.html.*",

    #

    # And the IUP homepage, which has some weird certificate settings

    r".*(www\.)?iup\.uni-heidelberg\.de/.*"

    r".*(www\.)?iup\.uni-heidelberg\.de/.*",

    #

    # Sites that do not allow the sphinx linkcheck client (403 client error)

    r".*(www\.)?intel\.com/.*",

]

        ``source`` object (a list).

    """

    if docname == "README":

        print("\nAdjusting README content ...")

        # Drop everything before the installation instructions

        marker = "<!-- marker-installation-instructions -->"

        new_start = source[0].find(marker) + len(marker)

        source[0] = "# Installation" + source[0][new_start:]

        # Text Replacements

        # ... to take care of changes in how the link slugs are created by myst

        print("Carrying out text replacements ...")

        source[0] = source[0].replace(

            "#3-configure-and-build", "#configure-and-build"

        )

        source[0] = source[0].replace(

            "../src/utopia/models",

            "https://gitlab.com/utopia-project/utopia/-/tree/master/src/utopia/models",

        )

        return

C++

---

We use C++17. For very recent coding guidelines on the new C++ standard(s), refer to

`CppCoreGuidelines <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md>`_ and

`Scott Meyers: Effective Modern C++ (2014) <https://moodle.ufsc.br/pluginfile.php/2377667/mod_resource/content/0/Effective_Modern_C__.pdf>`_.

We use C++17.

For very recent coding guidelines on the new C++ standard(s), refer to

`CppCoreGuidelines <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md>`_.

A good starter is also the *Effective Modern C++* book by Scott Meyers.

We will mostly stick to the STL library.

Its complete reference can be found on `cppreference.com <http://en.cppreference.com/w/>`_.

# Use a sphinx version that is compatible with sphinx-book-theme

Sphinx == 4.5.*

Sphinx == 5.*

# Extensions

sphinx-argparse