From 1ef15e33793f56b92d13a1a4e95d86cc9f25e4ed Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:29:20 +0100 Subject: [PATCH 01/39] CHG: add doxysphinx - remove exhale, breath --- .gitignore | 1 + .gitmodules | 3 +++ docs/Doxyfile | 22 +++++++++++----------- docs/doxygen-awesome-css | 1 + docs/source/conf.py | 17 ++++------------- docs/source/index.rst | 2 +- 6 files changed, 21 insertions(+), 25 deletions(-) create mode 100644 .gitmodules create mode 160000 docs/doxygen-awesome-css diff --git a/.gitignore b/.gitignore index 4984fd9aab..34e8473d18 100644 --- a/.gitignore +++ b/.gitignore @@ -282,6 +282,7 @@ docs/html docs/xml docs/source/api docs/source/generated +docs/source/cppapi # VS Code .vscode/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..10beb96517 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/doxygen-awesome-css"] + path = docs/doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/docs/Doxyfile b/docs/Doxyfile index 585872bc1e..6cb816bba9 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -32,13 +32,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "MEmilio" +PROJECT_NAME = "CPP API" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 0.7 +PROJECT_NUMBER = # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = source/cppapi # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -614,7 +614,7 @@ MAX_INITIALIZER_LINES = 30 # will mention the files that were used to generate the documentation. # The default value is: YES. -SHOW_USED_FILES = YES +SHOW_USED_FILES = NO # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This # will remove the Files entry from the Quick Index and from the Folder Tree View @@ -1058,7 +1058,7 @@ HTML_STYLESHEET = # see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ doxygen-awesome-css/doxygen-awesome-sidebar-only.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1456,7 +1456,7 @@ MATHJAX_CODEFILE = # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -SEARCHENGINE = YES +SEARCHENGINE = NO # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a web server instead of a web client using Javascript. There @@ -1969,7 +1969,7 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = +GENERATE_TAGFILE = source/cppapi/html/tagfile.xml # If the ALLEXTERNALS tag is set to YES all external class will be listed in the # class index. If set to NO only the inherited external classes will be listed. @@ -2032,7 +2032,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: NO. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2186,7 +2186,7 @@ DIRECTORY_GRAPH = YES # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -2198,7 +2198,7 @@ DOT_IMAGE_FORMAT = png # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = NO +INTERACTIVE_SVG = YES # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. @@ -2253,7 +2253,7 @@ MAX_DOT_GRAPH_DEPTH = 0 # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_TRANSPARENT = NO +DOT_TRANSPARENT = YES # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This diff --git a/docs/doxygen-awesome-css b/docs/doxygen-awesome-css new file mode 160000 index 0000000000..1f3620084f --- /dev/null +++ b/docs/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit 1f3620084ff75734ed192101acf40e9dff01d848 diff --git a/docs/source/conf.py b/docs/source/conf.py index d84900e917..aca85a8d17 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -34,9 +34,8 @@ 'sphinx_copybutton', 'sphinx_toolbox.collapse', 'sphinx_design', - 'breathe', - 'exhale', 'hoverxref.extension', + 'sphinxcontrib.doxylink', # 'sphinx_remove_toctrees' ] @@ -62,19 +61,11 @@ "class": "tooltip", } -exhale_args = { - "containmentFolder": "./api", - "rootFileName": "library_root.rst", - "doxygenStripFromPath": "..", - "rootFileTitle": "C++ API", - "createTreeView": True, - "treeViewIsBootstrap": False, - "contentsDirectives": False, +doxylink = { + "C++ API": ("source/cppapi/html/tagfile.xml", + "source/cppapi/html") } -breathe_projects = {"MEmilio": "../xml"} -breathe_default_project = "MEmilio" - # remove_from_toctrees = ["api/*"] templates_path = ['_templates'] diff --git a/docs/source/index.rst b/docs/source/index.rst index a8dff2648b..054ef15baa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -67,4 +67,4 @@ If you use MEmilio, please :doc:`cite our work`. :caption: Code API pythonapi/pythonapi - api/library_root + cppapi/html/index From 02fc473b58c2e335ee05603a314298b472a80861 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:41:05 +0100 Subject: [PATCH 02/39] FIX: build commands for rtd --- docs/requirements.txt | 2 ++ docs/source/conf.py | 1 + 2 files changed, 3 insertions(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index ea1593d382..669628c291 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,3 +9,5 @@ pycode/memilio-plot pycode/memilio-surrogatemodel exhale sphinx_toolbox +doxysphinx +sphinxcontrib-doxylink diff --git a/docs/source/conf.py b/docs/source/conf.py index aca85a8d17..744b4de3b2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,6 +19,7 @@ if read_the_docs_build: subprocess.call('cd ..; doxygen', shell=True) + subprocess.call('doxysphinx build . $READTHEDOCS_OUTPUT/html ../Doxyfile') # sys.path.insert(0, os.path.abspath('../../pycode')) From 624b0a1bd0eac71cf389684cb24b228607c2caa0 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:49:31 +0100 Subject: [PATCH 03/39] CHG: no xml output --- docs/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 6cb816bba9..1c33fc751d 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1769,7 +1769,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = YES +GENERATE_XML = NO # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of From a9af9c5da953811527d9ea5ffe5e4279c2d443f8 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:50:09 +0100 Subject: [PATCH 04/39] CHG: Try out rtd bash commands --- docs/source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 744b4de3b2..a8a63bb813 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,8 @@ if read_the_docs_build: subprocess.call('cd ..; doxygen', shell=True) - subprocess.call('doxysphinx build . $READTHEDOCS_OUTPUT/html ../Doxyfile') + subprocess.call('ls', shell = True) + subprocess.call('cd ..; doxysphinx build source $READTHEDOCS_OUTPUT/html Doxyfile', shell = True) # sys.path.insert(0, os.path.abspath('../../pycode')) From bf0e4a7bf69b8e96f1f6854fc38981bb435bf576 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:58:51 +0100 Subject: [PATCH 05/39] CHG: Add awesome doxygen --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a8a63bb813..76be1a1aa9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,8 +18,8 @@ if read_the_docs_build: + subprocess.call('cd ..; git submodule add https://github.com/jothepro/doxygen-awesome-css.git; cd doxygen-awesome-css; git checkout v2.4.1', shell=True) subprocess.call('cd ..; doxygen', shell=True) - subprocess.call('ls', shell = True) subprocess.call('cd ..; doxysphinx build source $READTHEDOCS_OUTPUT/html Doxyfile', shell = True) # sys.path.insert(0, os.path.abspath('../../pycode')) From e64e2e78fe00dc8871e0f360ea8c8e187986b5c0 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 17:04:51 +0100 Subject: [PATCH 06/39] CHG: Check awesome presence --- docs/source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 76be1a1aa9..8686b54c23 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,8 @@ if read_the_docs_build: - subprocess.call('cd ..; git submodule add https://github.com/jothepro/doxygen-awesome-css.git; cd doxygen-awesome-css; git checkout v2.4.1', shell=True) + # subprocess.call('cd ..; git submodule add https://github.com/jothepro/doxygen-awesome-css.git; cd doxygen-awesome-css; git checkout v2.4.1', shell=True) + subprocess.call('ls ../doxygen-awesome-css', shell=True) subprocess.call('cd ..; doxygen', shell=True) subprocess.call('cd ..; doxysphinx build source $READTHEDOCS_OUTPUT/html Doxyfile', shell = True) From f0c782b2bd08a7fac597f5880795420e135ad7b2 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 15 Jan 2026 17:11:27 +0100 Subject: [PATCH 07/39] FIX: load submodule --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8686b54c23..d2ed558fbe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,7 @@ if read_the_docs_build: # subprocess.call('cd ..; git submodule add https://github.com/jothepro/doxygen-awesome-css.git; cd doxygen-awesome-css; git checkout v2.4.1', shell=True) - subprocess.call('ls ../doxygen-awesome-css', shell=True) + subprocess.call('git submodule update --init --recursive', shell=True) subprocess.call('cd ..; doxygen', shell=True) subprocess.call('cd ..; doxysphinx build source $READTHEDOCS_OUTPUT/html Doxyfile', shell = True) From 54c0aed0c5ba47416ac34cb2c68b802cdd93f033 Mon Sep 17 00:00:00 2001 From: Carlotta Gerstein <100771374+charlie0614@users.noreply.github.com> Date: Tue, 3 Mar 2026 14:08:41 +0100 Subject: [PATCH 08/39] add build instruction for single target --- docs/source/getting_started.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 47e605c804..cd5a521f7e 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -195,6 +195,12 @@ you can use the ``-j`` flag (e.g., using 4 cores): cmake --build cpp/build +If you want to build a specific example, you can specify it with the ``--target`` flag: + +.. code-block:: console + + cmake --build . --target + If you experience errors, feel free to contact martin.kuehn@dlr.de or open a `discussion on GitHub `_! Running simulations From faa50c795fad5940f14f659f9e19d1efb8a802d4 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Wed, 4 Mar 2026 15:07:32 +0100 Subject: [PATCH 09/39] CHG: minor cleanup --- docs/Doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 280aeeb0ac..9ed4bda622 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1338,7 +1338,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ doxygen-awesome-css/doxygen-awesome-sidebar-only.css +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1402,7 +1402,7 @@ HTML_COLORSTYLE_GAMMA = 80 # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_MENUS = NO # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the From ed20bc0ee56cb33d4e7edb2049fdcc272a8b5b00 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Wed, 4 Mar 2026 15:07:54 +0100 Subject: [PATCH 10/39] CHG: test links --- docs/source/cpp/data_types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 54f0564667..2f3c19f215 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -52,4 +52,4 @@ The following list explains the nonstandard data types that are used throughout * - :code:`GeographicalLocation` - Stores coordinates in (Latitude, Longitude) format. Allows for comparisons and realistic distance calculations. * - :code:`Distance` - - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. + - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :MEmilio:`doxysphinx:kilometers` From 29da6197b9140706fe7572655f5521347b5116d7 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:14:13 +0100 Subject: [PATCH 11/39] CHG: remove related pages section --- docs/Doxyfile | 2 +- docs/DoxygenLayout.xml | 265 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 266 insertions(+), 1 deletion(-) create mode 100644 docs/DoxygenLayout.xml diff --git a/docs/Doxyfile b/docs/Doxyfile index 9ed4bda622..d1f535bb85 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -805,7 +805,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = +LAYOUT_FILE = DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml new file mode 100644 index 0000000000..eeb64a16ad --- /dev/null +++ b/docs/DoxygenLayout.xml @@ -0,0 +1,265 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 322f3c188101e92fabecab008c3db287a1e07ae0 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:19:29 +0100 Subject: [PATCH 12/39] CHG: Update doxysphinx role name --- docs/source/conf.py | 4 ++-- docs/source/cpp/data_types.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d2ed558fbe..9df01dba18 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,7 +39,7 @@ 'sphinx_design', 'hoverxref.extension', 'sphinxcontrib.doxylink', - # 'sphinx_remove_toctrees' +# 'sphinx_remove_toctrees' ] intersphinx_mapping = { @@ -65,7 +65,7 @@ } doxylink = { - "C++ API": ("source/cppapi/html/tagfile.xml", + "CPP-API": ("source/cppapi/html/tagfile.xml", "source/cppapi/html") } diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 2f3c19f215..90fd0a4bba 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -52,4 +52,4 @@ The following list explains the nonstandard data types that are used throughout * - :code:`GeographicalLocation` - Stores coordinates in (Latitude, Longitude) format. Allows for comparisons and realistic distance calculations. * - :code:`Distance` - - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :MEmilio:`doxysphinx:kilometers` + - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`doxysphinx:kilometers` From 32067f08e6afc36c6d68aa179c254d73a791ec0a Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:24:48 +0100 Subject: [PATCH 13/39] CHG: Update link --- docs/Doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index d1f535bb85..c3144e819f 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1004,7 +1004,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */README.md */*README* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -2436,7 +2436,7 @@ EXTERNAL_GROUPS = YES # be listed. # The default value is: YES. -EXTERNAL_PAGES = YES +EXTERNAL_PAGES = NO #--------------------------------------------------------------------------- # Configuration options related to diagram generator tools From 14dd7f4f4e1da43658ea44df9822fe8c086b5a9f Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:31:08 +0100 Subject: [PATCH 14/39] CHG: Update link --- docs/source/cpp/data_types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 90fd0a4bba..c1ccb0936e 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -52,4 +52,4 @@ The following list explains the nonstandard data types that are used throughout * - :code:`GeographicalLocation` - Stores coordinates in (Latitude, Longitude) format. Allows for comparisons and realistic distance calculations. * - :code:`Distance` - - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`doxysphinx:kilometers` + - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`doxysphinx::kilometers` From 1fd2937f9b3073d83ff43ab3ca98b391fc88e37e Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:31:18 +0100 Subject: [PATCH 15/39] FIX restore doxygen file --- docs/Doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index c3144e819f..ded9748c6f 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1004,7 +1004,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = */README.md */*README* +EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -2436,7 +2436,7 @@ EXTERNAL_GROUPS = YES # be listed. # The default value is: YES. -EXTERNAL_PAGES = NO +EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- # Configuration options related to diagram generator tools From a0806cb7d107e0db8583460a0daaa58b625a8e88 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:33:48 +0100 Subject: [PATCH 16/39] FIX: remove JAVA support --- docs/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index ded9748c6f..2385828850 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -289,7 +289,7 @@ OPTIMIZE_OUTPUT_FOR_C = NO # qualified scopes will look different, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_JAVA = YES +OPTIMIZE_OUTPUT_JAVA = NO # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. From 9c1e4ae71d4962e8a00818fc320308e74f1e0856 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:46:18 +0100 Subject: [PATCH 17/39] FIX link --- docs/source/cpp/data_types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index c1ccb0936e..6a8fc3def0 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -52,4 +52,4 @@ The following list explains the nonstandard data types that are used throughout * - :code:`GeographicalLocation` - Stores coordinates in (Latitude, Longitude) format. Allows for comparisons and realistic distance calculations. * - :code:`Distance` - - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`doxysphinx::kilometers` + - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`mio::geo::Distance::kilometers` From f612e52d4a574e627bef42ca0e0a7d9af8e140aa Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 09:55:46 +0100 Subject: [PATCH 18/39] CHG: replace included namespaces by links to docs --- docs/source/cpp/models/glsecir.rst | 6 +----- docs/source/cpp/models/isecir.rst | 5 +---- docs/source/cpp/models/iseir.rst | 6 +----- docs/source/cpp/models/lsecir.rst | 6 +----- docs/source/cpp/models/lsecir2d.rst | 5 +---- docs/source/cpp/models/omseirs4.rst | 2 ++ docs/source/cpp/models/oseair.rst | 5 +---- docs/source/cpp/models/osecir.rst | 5 ++--- docs/source/cpp/models/osecirts.rst | 4 +--- docs/source/cpp/models/osecirvvs.rst | 4 +--- docs/source/cpp/models/oseir.rst | 6 +----- docs/source/cpp/models/oseirdb.rst | 5 +---- docs/source/cpp/models/oseirv.rst | 5 +---- docs/source/cpp/models/osir.rst | 5 +---- docs/source/cpp/models/sseir.rst | 5 +---- docs/source/cpp/models/ssir.rst | 4 +--- docs/source/cpp/models/ssirs.rst | 5 +---- 17 files changed, 19 insertions(+), 64 deletions(-) diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index bed72acaae..3966d961d1 100644 --- a/docs/source/cpp/models/glsecir.rst +++ b/docs/source/cpp/models/glsecir.rst @@ -474,8 +474,4 @@ An example can be found at: - `examples/glct_secir.cpp `_ - -Overview of the ``glsecir`` namespace: --------------------------------------- - -.. doxygennamespace:: mio::glsecir +and the code documentation for the model at :CPP-API:`mio::glsecir` . diff --git a/docs/source/cpp/models/isecir.rst b/docs/source/cpp/models/isecir.rst index 0ec2fcbf40..9df8194094 100644 --- a/docs/source/cpp/models/isecir.rst +++ b/docs/source/cpp/models/isecir.rst @@ -371,7 +371,4 @@ Different examples can be found at: - `examples/ide_secir_ageres.cpp `_ - `examples/ide_initialization.cpp `_ -Overview of the ``isecir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::isecir +The code documentation for the model can be found at :CPP-API:`mio::isecir` . diff --git a/docs/source/cpp/models/iseir.rst b/docs/source/cpp/models/iseir.rst index 8b5bfaa545..d1b6714848 100644 --- a/docs/source/cpp/models/iseir.rst +++ b/docs/source/cpp/models/iseir.rst @@ -178,8 +178,4 @@ An example can be found at: - `examples/ide_seir.cpp `_ - -Overview of the ``iseir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::iseir \ No newline at end of file +The code documentation for the model can be found at :CPP-API:`mio::iseir` . diff --git a/docs/source/cpp/models/lsecir.rst b/docs/source/cpp/models/lsecir.rst index 5f1e6fd95d..3ccbc98152 100644 --- a/docs/source/cpp/models/lsecir.rst +++ b/docs/source/cpp/models/lsecir.rst @@ -355,8 +355,4 @@ An example can be found at: - `examples/lct_secir.cpp `_ - -Overview of the ``lsecir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::lsecir +The code documentation for the model can be found at :CPP-API:`mio::lsecir` . diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index f312147e6b..9bc60c71af 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -460,7 +460,4 @@ An example can be found at: - `examples/lct_secir_2_diseases.cpp `_ -Overview of the ``lsecir2d`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::lsecir2d +The code documentation for the model can be found at :CPP-API:`mio::lsecir2d` . diff --git a/docs/source/cpp/models/omseirs4.rst b/docs/source/cpp/models/omseirs4.rst index 937e04b559..17b7cb216a 100644 --- a/docs/source/cpp/models/omseirs4.rst +++ b/docs/source/cpp/models/omseirs4.rst @@ -114,6 +114,8 @@ Initial conditions are absolute counts in each InfectionState; totals may be set Example (see `examples/ode_mseirs4.cpp `_) shows a complete initialization and simulation. +The code documentation for the model can be found at :CPP-API:`mio::omseirs4` . + Simulation ---------- diff --git a/docs/source/cpp/models/oseair.rst b/docs/source/cpp/models/oseair.rst index c4ad6b4312..ac08fc4a6b 100644 --- a/docs/source/cpp/models/oseair.rst +++ b/docs/source/cpp/models/oseair.rst @@ -62,7 +62,4 @@ Below is an overview of the model architecture and its compartments. `examples/ode_seair_optimization.cpp `_. -Overview of the ``oseair`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::oseair +The code documentation for the model can be found at :CPP-API:`mio::oseair` . diff --git a/docs/source/cpp/models/osecir.rst b/docs/source/cpp/models/osecir.rst index 4b09ff166b..58541e2f6f 100644 --- a/docs/source/cpp/models/osecir.rst +++ b/docs/source/cpp/models/osecir.rst @@ -388,7 +388,6 @@ Different examples can be found at: - `examples/ode_secir_ageres.cpp `_ - `examples/ode_secir_parameter_study.cpp `_ -Overview of the ``osecir`` namespace: ------------------------------------------ -.. doxygennamespace:: mio::osecir +The code documentation for the model can be found at :CPP-API:`mio::osecir` . + diff --git a/docs/source/cpp/models/osecirts.rst b/docs/source/cpp/models/osecirts.rst index 2944d027c9..36dec27a15 100644 --- a/docs/source/cpp/models/osecirts.rst +++ b/docs/source/cpp/models/osecirts.rst @@ -401,7 +401,5 @@ Examples To get started with the ODE-SECIRTS model, check out the code example in the MEmilio repository: `examples/ode_secirts.cpp `_. -Overview of the ``osecirts`` namespace: ------------------------------------------ -.. doxygennamespace:: mio::osecirts +The code documentation for the model can be found at :CPP-API:`mio::osecirts` . \ No newline at end of file diff --git a/docs/source/cpp/models/osecirvvs.rst b/docs/source/cpp/models/osecirvvs.rst index e516b005ee..edafde4adc 100644 --- a/docs/source/cpp/models/osecirvvs.rst +++ b/docs/source/cpp/models/osecirvvs.rst @@ -425,7 +425,5 @@ Examples of the basic ODE-SECIR model can be found at: - `examples/ode_secir_ageres.cpp `_ - `examples/ode_secir_parameter_study.cpp `_ -Overview of the ``osecirvvs`` namespace: ------------------------------------------ -.. doxygennamespace:: mio::osecirvvs +The code documentation for the model can be found at :CPP-API:`mio::osecirvvs` . diff --git a/docs/source/cpp/models/oseir.rst b/docs/source/cpp/models/oseir.rst index 417ed98e89..a22075ea7d 100644 --- a/docs/source/cpp/models/oseir.rst +++ b/docs/source/cpp/models/oseir.rst @@ -258,8 +258,4 @@ Examples An example can be found at `examples/ode_seir.cpp `_. - -Overview of the ``oseir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::oseir +The code documentation for the model can be found at :CPP-API:`mio::oseir` . diff --git a/docs/source/cpp/models/oseirdb.rst b/docs/source/cpp/models/oseirdb.rst index cab9d4a710..809dbda49c 100644 --- a/docs/source/cpp/models/oseirdb.rst +++ b/docs/source/cpp/models/oseirdb.rst @@ -258,7 +258,4 @@ An example can be found at `examples/ode_seirdb.cpp `_. -Overview of the ``oseir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::oseirdb +The code documentation for the model can be found at :CPP-API:`mio::oseirdb` . diff --git a/docs/source/cpp/models/oseirv.rst b/docs/source/cpp/models/oseirv.rst index 8bfb609eef..b0bff91a3b 100644 --- a/docs/source/cpp/models/oseirv.rst +++ b/docs/source/cpp/models/oseirv.rst @@ -238,7 +238,4 @@ Literature * Weidemann, F., Remschmidt, C., Buda, S. et al. *Is the impact of childhood influenza vaccination less than expected: a transmission modelling study.* BMC Infectious Diseases 17, 258 (2017). https://doi.org/10.1186/s12879-017-2344-6 -Overview of the ``oseirv`` namespace: -------------------------------------- - -.. doxygennamespace:: mio::oseirv +The code documentation for the model can be found at :CPP-API:`mio::oseirv` . diff --git a/docs/source/cpp/models/osir.rst b/docs/source/cpp/models/osir.rst index ce97249807..c7d0ce4614 100644 --- a/docs/source/cpp/models/osir.rst +++ b/docs/source/cpp/models/osir.rst @@ -208,7 +208,4 @@ Examples An example can be found at `examples/ode_sir.cpp `_. -Overview of the ``osir`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::osir +The code documentation for the model can be found at :CPP-API:`mio::osir` . diff --git a/docs/source/cpp/models/sseir.rst b/docs/source/cpp/models/sseir.rst index c6eec4cf33..83a2b99534 100644 --- a/docs/source/cpp/models/sseir.rst +++ b/docs/source/cpp/models/sseir.rst @@ -47,7 +47,4 @@ The simulation runs in discrete time steps using an Euler-Maruyama integration s An example can be found in `examples/sde_seirvv.cpp `_ -Overview of the ``sseirvv`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::sseirvv \ No newline at end of file +The code documentation for the model can be found at :CPP-API:`mio::sseirvv` . diff --git a/docs/source/cpp/models/ssir.rst b/docs/source/cpp/models/ssir.rst index b4b2031cbf..977524066a 100644 --- a/docs/source/cpp/models/ssir.rst +++ b/docs/source/cpp/models/ssir.rst @@ -30,7 +30,5 @@ Mathematical variable C++ variable name Description An example can be found in `sde_sir.cpp `_ -Overview of the ``SSIR`` namespace: ------------------------------------- -.. doxygennamespace:: mio::ssir +The code documentation for the model can be found at :CPP-API:`mio::ssir` . diff --git a/docs/source/cpp/models/ssirs.rst b/docs/source/cpp/models/ssirs.rst index 2e17196cee..db6a62f792 100644 --- a/docs/source/cpp/models/ssirs.rst +++ b/docs/source/cpp/models/ssirs.rst @@ -36,7 +36,4 @@ An example can be found in the `examples/ode_sir.cpp `_. -Overview of the ``ssirs`` namespace: ------------------------------------------ - -.. doxygennamespace:: mio::ssirs +The code documentation for the model can be found at :CPP-API:`mio::ssirs` . From 744d3de0d70023226ec6fcfc4dc1c4b16e80fe52 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:08:43 +0100 Subject: [PATCH 19/39] CHG: try different links --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9df01dba18..37c2929fb0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -66,7 +66,7 @@ doxylink = { "CPP-API": ("source/cppapi/html/tagfile.xml", - "source/cppapi/html") + "../../source/cppapi/html") } # remove_from_toctrees = ["api/*"] From 72ce6af1b0b0dd65761b9631a6d2f81fad69cef1 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:21:13 +0100 Subject: [PATCH 20/39] CHG: Try guess rtd links --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 37c2929fb0..a24936ffe8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,8 +65,8 @@ } doxylink = { - "CPP-API": ("source/cppapi/html/tagfile.xml", - "../../source/cppapi/html") + "CPP-API": ("/html/source/cppapi/html/tagfile.xml", + "/html/source/cppapi/html") } # remove_from_toctrees = ["api/*"] From 3d6ddf78ecc8f6536475b90b8f90bd988e00bc22 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:26:49 +0100 Subject: [PATCH 21/39] retry --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a24936ffe8..9df01dba18 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,8 +65,8 @@ } doxylink = { - "CPP-API": ("/html/source/cppapi/html/tagfile.xml", - "/html/source/cppapi/html") + "CPP-API": ("source/cppapi/html/tagfile.xml", + "source/cppapi/html") } # remove_from_toctrees = ["api/*"] From 75528eb5344ba24ede04b0f95f237199a9b19e96 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:35:58 +0100 Subject: [PATCH 22/39] retry --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9df01dba18..526a02905e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,8 +65,8 @@ } doxylink = { - "CPP-API": ("source/cppapi/html/tagfile.xml", - "source/cppapi/html") + "CPP-API": ("cppapi/html/tagfile.xml", + "cppapi/html") } # remove_from_toctrees = ["api/*"] From 78dc38ca45140de1b66dd4a70e73f4686a9bd793 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:45:38 +0100 Subject: [PATCH 23/39] CHG: replace inline namespace docs by link --- docs/source/cpp/diffusive_abm.rst | 7 +------ docs/source/cpp/smm.rst | 7 +------ 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/docs/source/cpp/diffusive_abm.rst b/docs/source/cpp/diffusive_abm.rst index 6df63ef139..d56323f858 100644 --- a/docs/source/cpp/diffusive_abm.rst +++ b/docs/source/cpp/diffusive_abm.rst @@ -182,9 +182,4 @@ Examples An example of the diffusive ABM using the quadwell potential can be found at: `examples/d_abm.cpp `_ - -Overview of the ``dabm`` namespace: ------------------------------------ - -.. doxygennamespace:: mio::dabm - +The code documentation for the model can be found at :CPP-API:`mio::dabm` . diff --git a/docs/source/cpp/smm.rst b/docs/source/cpp/smm.rst index bbed8cb139..bf37788a75 100644 --- a/docs/source/cpp/smm.rst +++ b/docs/source/cpp/smm.rst @@ -265,9 +265,4 @@ Examples A full example with ``Status`` including ``InfectionState``, ``Age`` and ``Species`` can be found at `examples/smm.cpp `_ - - -Overview of the ``smm`` namespace: ------------------------------------ - -.. doxygennamespace:: mio::smm +The code documentation for the model can be found at :CPP-API:`mio::smm` . From 423048700c685875c509a64980e49b38a5613349 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 12:38:16 +0100 Subject: [PATCH 24/39] Add local setup --- docs/source/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 526a02905e..c8132ad515 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -64,10 +64,16 @@ "class": "tooltip", } +# doxylink readthedocs setup: doxylink = { "CPP-API": ("cppapi/html/tagfile.xml", "cppapi/html") } +#doxylink local setup: +# doxylink = { +# "CPP-API": ("source/cppapi/html/tagfile.xml", +# "../../source/cppapi/html") +# } # remove_from_toctrees = ["api/*"] From be15e9cdaa59a72391b6db512252841d20cf2ec3 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 12:38:42 +0100 Subject: [PATCH 25/39] Update development guidelines --- docs/source/development.rst | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index 3c800717df..c8e5824420 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -1,5 +1,5 @@ Developer workflow -======================== +================== We are always happy about contributions to the project! Here you can find more information on our coding guidelines, our git workflow, benchmarking our models and writing documentation. @@ -352,13 +352,26 @@ The full list of labels that should be used to identify issues can be found at: Documentation -------------------- -The documentation uses `Sphinx `_ and is written in reStructuredText, that uses a +The documentation uses `Sphinx `_ and is written in reStructuredText (rst), that uses a slightly different syntax than Markdown. A documentation can be found `here `_. This online documentation is generated using `ReadTheDocs `_ and is automatically updated when a pull request is merged into the main branch. Thus, we require you to build the documentation locally to test changes. Literature is centrally collected in `literature.rst` and `substitutions `_ are used to print it wherever needed. +The C++ Code documentation is generated using `doxygen `_, visually improved by `doxygen-awesome-css `_ +and included using `doxysphinx `_ . Links to the C++ docs from within the +rst files can be generated as in the following examples: + +.. code-block:: rst + + :CPP-API:`mio::osir` + :CPP-API:`mio::geo::Distance::kilometers` + :CPP-API:`Graph Constructor ` + .. opening angle brackets in the function defintion need to be escaped, the following line is also sensitive to the space between the closing brackets + :CPP-API:`mio::details::SimulationBase\< FP, M, SystemIntegrator\< FP, Integrands... > >` + + Please make sure to have a working python environment with a python version that is compatible with our :doc:`memilio-python packages ` as well as all packages listed in ``docs/requirements.txt`` and `doxygen `_ installed. @@ -371,8 +384,8 @@ First generate the doxygen output by running doxygen -In the ``docs/Doxyfile`` (line 736), you can change for which folders the doxygen output should be generated. For faster -build times while testing we recommend to only use e.g. ``../cpp/models/abm``. **Don't commit this change!** +To test links to the C++ documentation, you need to point sphinx to the correct files. These are given in the `conf.py` +file as the `doxylink = ... ` settings. **Don't commit this change!** Then sphinx can be used to build the documentation: From bb94b766969ff29cd64dc91a799fa22cf0de6f54 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 12:43:24 +0100 Subject: [PATCH 26/39] FIX: code blokc in GLCT --- docs/source/cpp/glct.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/source/cpp/glct.rst b/docs/source/cpp/glct.rst index 47d019ad35..05e6ef7c34 100644 --- a/docs/source/cpp/glct.rst +++ b/docs/source/cpp/glct.rst @@ -25,9 +25,7 @@ parameter to the model. .. code-block:: cpp - using LctStateGroup1 = mio::LctInfectionState; + using LctStateGroup1 = mio::LctInfectionState; The model is implemented as **CompartmentalModel**. From 2653dcbe7c8afb441d8642fd54b722e5e77d9715 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 12:44:00 +0100 Subject: [PATCH 27/39] CHG: remove README as main file for cpp api --- docs/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 2385828850..d982a6fa60 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1099,7 +1099,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = ../README.md +USE_MDFILE_AS_MAINPAGE = # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common From 93d681eaf31fab8a721143f17b2c80641cc0ed1c Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 13:07:25 +0100 Subject: [PATCH 28/39] CHG: try startpage --- docs/Doxyfile | 2 +- docs/doxygen_main_page.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 docs/doxygen_main_page.md diff --git a/docs/Doxyfile b/docs/Doxyfile index d982a6fa60..238f7ea4f2 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1099,7 +1099,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = ../docs/doxygen_main_page.md # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common diff --git a/docs/doxygen_main_page.md b/docs/doxygen_main_page.md new file mode 100644 index 0000000000..c317661326 --- /dev/null +++ b/docs/doxygen_main_page.md @@ -0,0 +1 @@ +On these pages you can find the documentation for our C++ code. Navigation is easiest by the top bar. If you search for a specific function, we recommend using the search bar. \ No newline at end of file From dbf5ed80bb7fdbe8391f66bf96cdab76c36eb64e Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 13:17:19 +0100 Subject: [PATCH 29/39] FIX: parse main page file --- docs/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 238f7ea4f2..317bf9c633 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -933,7 +933,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../cpp/models ../cpp/memilio ../cpp/sbml_model_generation +INPUT = ../cpp/models ../cpp/memilio ../cpp/sbml_model_generation ../docs/doxygen_main_page.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses From 9bb9c48865183b17c3498b5d9f24b291b0bb787f Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 13:28:40 +0100 Subject: [PATCH 30/39] NEW: workflow for docs preview --- .github/workflows/documentation_links.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .github/workflows/documentation_links.yml diff --git a/.github/workflows/documentation_links.yml b/.github/workflows/documentation_links.yml new file mode 100644 index 0000000000..7d4412f8b4 --- /dev/null +++ b/.github/workflows/documentation_links.yml @@ -0,0 +1,16 @@ +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "memilio" \ No newline at end of file From 965d2d3183f7bcd4b6c3bae0865b9ad32efeac44 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 13:35:26 +0100 Subject: [PATCH 31/39] FIX: link layout --- docs/source/development.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index c8e5824420..52749f7b6c 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -384,8 +384,8 @@ First generate the doxygen output by running doxygen -To test links to the C++ documentation, you need to point sphinx to the correct files. These are given in the `conf.py` -file as the `doxylink = ... ` settings. **Don't commit this change!** +To test links to the C++ documentation, you need to point sphinx to the correct files. These are given in the ``conf.py`` +file as the ``doxylink = ... `` settings. **Don't commit this change!** Then sphinx can be used to build the documentation: From eda87b18dcae3a3afd414838c2bab587be72e128 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 14:46:36 +0100 Subject: [PATCH 32/39] CHG: add hint at docs preview --- .github/pull_request_template.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a53c48c1b2..dca7b29bc2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,19 +18,19 @@ Please check our [git workflow](https://memilio.readthedocs.io/en/latest/develop ### Checks by code author -- [ ] Every addressed issue is linked (use the "Closes #ISSUE" keyword below) -- [ ] New code adheres to [coding guidelines](https://memilio.readthedocs.io/en/latest/development.html#coding-guidelines) -- [ ] No large data files have been added (files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.) -- [ ] Tests are added for new functionality and a local test run was successful (with and without OpenMP) -- [ ] Appropriate **documentation within the code** (Doxygen) for new functionality has been added in the code -- [ ] Appropriate **external documentation** (ReadTheDocs) for new functionality has been added to the online documentation -- [ ] Proper attention to licenses, especially no new third-party software with conflicting license has been added +- [ ] Every addressed issue is linked (use the "Closes #ISSUE" keyword below). +- [ ] New code adheres to [coding guidelines](https://memilio.readthedocs.io/en/latest/development.html#coding-guidelines). +- [ ] No large data files have been added (files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.). +- [ ] Tests are added for new functionality and a local test run was successful (with and without OpenMP). +- [ ] Appropriate **documentation within the code** (Doxygen) for new functionality has been added in the code. +- [ ] Appropriate **external documentation** (ReadTheDocs) for new functionality has been added to the online documentation and checked in the preview. +- [ ] Proper attention to licenses, especially no new third-party software with conflicting license has been added. - [ ] (For ABM development) Checked [benchmark results](https://memilio.readthedocs.io/en/latest/development.html#agent-based-model-development) and ran and posted a local test above from before and after development to ensure performance is monitored. ### Checks by code reviewer(s) -- [ ] Corresponding issue(s) is/are linked and addressed -- [ ] Code is clean of development artifacts (no deactivated or commented code lines, no debugging printouts, etc.) -- [ ] Appropriate **unit tests** have been added, CI passes, code coverage and performance is acceptable (did not decrease) -- [ ] No large data files added in the whole history of commits(files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.) +- [ ] Corresponding issue(s) is/are linked and addressed. +- [ ] Code is clean of development artifacts (no deactivated or commented code lines, no debugging printouts, etc.). +- [ ] Appropriate **unit tests** have been added, CI passes, code coverage and performance is acceptable (did not decrease). +- [ ] No large data files added in the whole history of commits(files should in sum not exceed 100 KB, avoid PDFs, Word docs, etc.). - [ ] On merge, add 2-5 lines with the changes (main added features, changed items, or corrected bugs) to the merge-commit-message. This can be taken from the **briefly-list-the-changes** above (best case) or the separate commit messages (worst case). From bb2e886a32cab2b97ffffef0db034b18ca2293ea Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 15:15:26 +0100 Subject: [PATCH 33/39] [ci skip] fix layout --- docs/source/development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index 52749f7b6c..30b770cd7a 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -385,7 +385,7 @@ First generate the doxygen output by running To test links to the C++ documentation, you need to point sphinx to the correct files. These are given in the ``conf.py`` -file as the ``doxylink = ... `` settings. **Don't commit this change!** +file as the ``doxylink = ...`` settings. **Don't commit this change!** Then sphinx can be used to build the documentation: From 9e5ac4ac7e3e00f57ef6c2278296799224455e68 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 15:16:42 +0100 Subject: [PATCH 34/39] CHG: remove workflow attempt --- .github/workflows/documentation_links.yml | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 .github/workflows/documentation_links.yml diff --git a/.github/workflows/documentation_links.yml b/.github/workflows/documentation_links.yml deleted file mode 100644 index 7d4412f8b4..0000000000 --- a/.github/workflows/documentation_links.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: readthedocs/actions -on: - pull_request_target: - types: - - opened - -permissions: - pull-requests: write - -jobs: - documentation-links: - runs-on: ubuntu-latest - steps: - - uses: readthedocs/actions/preview@v1 - with: - project-slug: "memilio" \ No newline at end of file From 6074f51a110b34a259e572d17f1d4b1a0b714b1d Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 15:25:28 +0100 Subject: [PATCH 35/39] [skip ci] Update development with regards to pull request builds --- docs/source/development.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index 30b770cd7a..189a4095f0 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -350,12 +350,13 @@ The full list of labels that should be used to identify issues can be found at: Documentation --------------------- +------------- The documentation uses `Sphinx `_ and is written in reStructuredText (rst), that uses a slightly different syntax than Markdown. A documentation can be found `here `_. This online documentation is generated using `ReadTheDocs `_ and is automatically updated when -a pull request is merged into the main branch. Thus, we require you to build the documentation locally to test changes. +a pull request is merged into the main branch. For Pull Requests, a new version of the documentation is built on a second +server by ReadTheDocs. The checks include the build status and a link to the new documentation. Literature is centrally collected in `literature.rst` and `substitutions `_ are used to print it wherever needed. @@ -372,7 +373,7 @@ rst files can be generated as in the following examples: :CPP-API:`mio::details::SimulationBase\< FP, M, SystemIntegrator\< FP, Integrands... > >` -Please make sure to have a working python environment with a python version that is compatible with +For a local build, please make sure to have a working python environment with a python version that is compatible with our :doc:`memilio-python packages ` as well as all packages listed in ``docs/requirements.txt`` and `doxygen `_ installed. From a134fd369e6d4ed119e95b8cdbed17bce2b7148f Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 15:37:44 +0100 Subject: [PATCH 36/39] CHG: link to distance instead of kilometer --- docs/source/cpp/data_types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 6a8fc3def0..417cf04558 100644 --- a/docs/source/cpp/data_types.rst +++ b/docs/source/cpp/data_types.rst @@ -52,4 +52,4 @@ The following list explains the nonstandard data types that are used throughout * - :code:`GeographicalLocation` - Stores coordinates in (Latitude, Longitude) format. Allows for comparisons and realistic distance calculations. * - :code:`Distance` - - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`mio::geo::Distance::kilometers` + - Represents a distance. Internally, all distances are stored in meters. They can be created from meters or kilometers and they can be exported using both units. See :CPP-API:`mio::geo::Distance` From 48985bd44bfa3387a6f105b9182b8454433c2849 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Thu, 5 Mar 2026 16:18:52 +0100 Subject: [PATCH 37/39] [ci skip] FIX: include image correctly --- docs/source/cpp/models/lsecir2d.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cpp/models/lsecir2d.rst b/docs/source/cpp/models/lsecir2d.rst index 9bc60c71af..ad96e8cda6 100644 --- a/docs/source/cpp/models/lsecir2d.rst +++ b/docs/source/cpp/models/lsecir2d.rst @@ -16,7 +16,7 @@ so the full model is given by the combination of infections :math:`1a`, :math:`2 Below is a visualization of the infection states split into LCT-states and transitions without a stratification according to sociodemographic groups. -.. image:: "http://martinkuehn.eu/research/images/lct_2d.png" +.. image:: http://martinkuehn.eu/research/images/lct_2d.png :alt: tikz_lct-2d With infection states for :math:`i \in \{1,2\}, x \in \{a,b\}`: From 89879a4eb75c7f7b13b7be57f745f6e5e2fafe40 Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Wed, 11 Mar 2026 17:15:53 +0100 Subject: [PATCH 38/39] Apply suggestions from code review Co-authored-by: Henrik Zunker <69154294+HenrZu@users.noreply.github.com> --- docs/source/conf.py | 1 - docs/source/cpp/models/glsecir.rst | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c8132ad515..5e3ea7ba4a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,6 @@ if read_the_docs_build: - # subprocess.call('cd ..; git submodule add https://github.com/jothepro/doxygen-awesome-css.git; cd doxygen-awesome-css; git checkout v2.4.1', shell=True) subprocess.call('git submodule update --init --recursive', shell=True) subprocess.call('cd ..; doxygen', shell=True) subprocess.call('cd ..; doxysphinx build source $READTHEDOCS_OUTPUT/html Doxyfile', shell = True) diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index 3966d961d1..f7a1072fa8 100644 --- a/docs/source/cpp/models/glsecir.rst +++ b/docs/source/cpp/models/glsecir.rst @@ -474,4 +474,4 @@ An example can be found at: - `examples/glct_secir.cpp `_ -and the code documentation for the model at :CPP-API:`mio::glsecir` . +The code documentation for the model can be found at :CPP-API:`mio::glsecir` . From 0bf13b08744bf8f06e08cca0f457d187aa92a88f Mon Sep 17 00:00:00 2001 From: Kilian Volmer <13285635+kilianvolmer@users.noreply.github.com> Date: Wed, 11 Mar 2026 17:19:43 +0100 Subject: [PATCH 39/39] [ci skip] remove breath and exhale from requirements --- docs/requirements.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 669628c291..91883ac379 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,12 +2,10 @@ sphinx==7.1.2 sphinx-rtd-theme==1.3.0rc1 sphinx-copybutton sphinx_design -breathe sphinx-hoverxref pycode/memilio-epidata pycode/memilio-plot pycode/memilio-surrogatemodel -exhale sphinx_toolbox doxysphinx sphinxcontrib-doxylink