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). 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 37fb9ce574..317bf9c633 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -42,13 +42,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 @@ -68,7 +68,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 up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -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. @@ -767,7 +767,7 @@ MAX_INITIALIZER_LINES = 30 # list 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 @@ -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 @@ -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 @@ -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 = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -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 = ../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 @@ -1338,7 +1338,7 @@ HTML_STYLESHEET = # 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 # 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 @@ -1833,7 +1833,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 @@ -2193,7 +2193,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 @@ -2415,7 +2415,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 classes and namespaces # will be listed in the class and namespace index. If set to NO, only the @@ -2455,7 +2455,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: YES. -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 @@ -2677,7 +2677,7 @@ DIR_GRAPH_MAX_DEPTH = 1 # 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. @@ -2689,7 +2689,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. 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index ea1593d382..91883ac379 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,10 +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 diff --git a/docs/source/conf.py b/docs/source/conf.py index d84900e917..5e3ea7ba4a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,9 @@ if read_the_docs_build: + 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) # sys.path.insert(0, os.path.abspath('../../pycode')) @@ -34,10 +36,9 @@ 'sphinx_copybutton', 'sphinx_toolbox.collapse', 'sphinx_design', - 'breathe', - 'exhale', 'hoverxref.extension', - # 'sphinx_remove_toctrees' + 'sphinxcontrib.doxylink', +# 'sphinx_remove_toctrees' ] intersphinx_mapping = { @@ -62,18 +63,16 @@ "class": "tooltip", } -exhale_args = { - "containmentFolder": "./api", - "rootFileName": "library_root.rst", - "doxygenStripFromPath": "..", - "rootFileTitle": "C++ API", - "createTreeView": True, - "treeViewIsBootstrap": False, - "contentsDirectives": False, +# doxylink readthedocs setup: +doxylink = { + "CPP-API": ("cppapi/html/tagfile.xml", + "cppapi/html") } - -breathe_projects = {"MEmilio": "../xml"} -breathe_default_project = "MEmilio" +#doxylink local setup: +# doxylink = { +# "CPP-API": ("source/cppapi/html/tagfile.xml", +# "../../source/cppapi/html") +# } # remove_from_toctrees = ["api/*"] diff --git a/docs/source/cpp/data_types.rst b/docs/source/cpp/data_types.rst index 54f0564667..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. + - 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` 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/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**. diff --git a/docs/source/cpp/models/glsecir.rst b/docs/source/cpp/models/glsecir.rst index bed72acaae..f7a1072fa8 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 +The code documentation for the model can be found 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..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\}`: @@ -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` . 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` . diff --git a/docs/source/development.rst b/docs/source/development.rst index 3c800717df..189a4095f0 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. @@ -350,16 +350,30 @@ 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. +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. -Please make sure to have a working python environment with a python version that is compatible with +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... > >` + + +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. @@ -371,8 +385,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: 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 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