Add sphinx docs

.github/workflows/doc.yml

@@ -11,6 +11,7 @@ on:
   pull_request: 
     branches: 
       - master
+      - develop
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }} 
@@ -25,7 +26,7 @@ jobs:
        with:
           persist-credentials: false
      - name: installPackages
-       run: sudo apt-get install --no-install-recommends --yes doxygen
+       run: sudo apt-get install --no-install-recommends --yes doxygen graphviz
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x' # Version range or exact version of a Python version to use, using SemVer's version range syntax
@@ -38,10 +39,22 @@ jobs:
      - run: python3 Setup.py --build-missing
      - run: cmake --preset conan-linux-x86_64-release
      - run: cmake --build --preset conan-linux-x86_64-release -j${{ steps.cpu-cores.outputs.count }} -t doc
+
+     # sphinx
+     - run: pip3 install sphinx pipenv breathe myst_parser sphinx_github_changelog sphinx_rtd_dark_mode
+     - run: python3 docs/build_sphinx.py ./build/linux-x86_64-release/xml
+
+
+
      - uses: actions/upload-artifact@v4
        with:
         path: build/linux-x86_64-release/html
-        name: documentation
+        name: doxygen
+
+     - uses: actions/upload-artifact@v4
+       with:
+        path: docs/_build
+        name: sphinx
 
   UploadDocumentation:
     if:   github.event_name == 'push' && github.ref == 'refs/heads/master'
@@ -51,11 +64,23 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/download-artifact@v4
         with:
-          name: documentation
-          path: documentation
+          name: doxygen
+          path: doxygen
+      - uses: actions/download-artifact@v4
+        with:
+          name: sphinx
+          path: sphinx
+
       - name: Deploy
         uses: JamesIves/[email protected]
         with:
             branch: gh-pages # The branch the action should deploy to.
-            folder: documentation # The folder the action should deploy.
+            folder: doxygen # The folder the action should deploy.
             target-folder: documentation
+
+      - name: Deploy
+        uses: JamesIves/[email protected]
+        with:
+            branch: gh-pages # The branch the action should deploy to.
+            folder: sphinx # The folder the action should deploy.
+            target-folder: sphinx

.gitignore

@@ -16,4 +16,6 @@ analyze*.py
 *.synctex.gz
 
 CMakeUserPresets.json
-__pycache__/*
+*/__pycache__/*
+docs/_build/*
+Pipfile

CMakeLists.txt

@@ -195,36 +195,7 @@ endif()
 
 # ------------------------ Doxygen --------------------------------------------
 if(BSMPT_IS_TOPLEVEL)
-  find_package(Doxygen)
-  if(DOXYGEN_FOUND)
-
-    set(DOXYGEN_USE_MATHJAX YES)
-    set(DOXYGEN_STRIP_FROM_INC_PATH "${CMAKE_CURRENT_SOURCE_DIR}/include")
-    set(DOXYGEN_EXCLUDE
-        ${CMAKE_CURRENT_SOURCE_DIR}/src/Kfactors/Kfunctions_grid_Part1.cpp
-        ${CMAKE_CURRENT_SOURCE_DIR}/src/Kfactors/Kfunctions_grid_Part2.cpp)
-    set(DOXYGEN_EXCLUDE_PATTERNS ${CMAKE_CURRENT_SOURCE_DIR}/src/*/README.md)
-    set(DOXYGEN_PROJECT_BRIEF ${CMAKE_PROJECT_DESCRIPTION})
-    set(DOXYGEN_EXTRACT_PRIVATE YES)
-    set(DOXYGEN_GENERATE_TREEVIEW YES)
-    set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)
-    set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
-    set(DOXYGEN_WARN_IF_DOC_ERROR YES)
-    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
-
-    doxygen_add_docs(
-      doc
-      "${CMAKE_CURRENT_SOURCE_DIR}/include/"
-      "${CMAKE_CURRENT_SOURCE_DIR}/src/"
-      "${CMAKE_CURRENT_SOURCE_DIR}/README.md"
-      "${CMAKE_CURRENT_SOURCE_DIR}/Changelog.md"
-      "${CMAKE_CURRENT_SOURCE_DIR}/tests/")
-
-  else()
-    message(
-      "Doxygen need to be installed to generate the doxygen documentation")
-  endif()
-
+  include(Doxygen)
 endif(BSMPT_IS_TOPLEVEL)
 
 # -------------------- Testing

README.md

@@ -11,7 +11,8 @@ Released by: Philipp Basler, Lisa Biermann, Margarete Mühlleitner, Jonas Mülle
 [![GitHub Discussions](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/phbasler/BSMPT/discussions)
 [![Unit tests](https://github.com/phbasler/BSMPT/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/phbasler/BSMPT/actions/workflows/test.yml)
 [![codecov master](https://codecov.io/gh/phbasler/BSMPT/branch/master/graph/badge.svg?token=LDGNQTADB5)](https://codecov.io/gh/phbasler/BSMPT)
-[![Documentation](https://img.shields.io/badge/Documentation-master-success)][DoxygenLink]
+[![Doxygen Documentation](https://img.shields.io/badge/Documentation-master-success)][DoxygenLink]
+[![Documentation](https://img.shields.io/badge/Documentation-master-success)][SphinxLink]
 [![Benchmarks](https://img.shields.io/badge/Benchmark-master-success)](https://phbasler.github.io/BSMPT/benchmarks/)
 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/phbasler/bsmpt/graphs/commit-activity)
 [![GitHub license](https://img.shields.io/github/license/phbasler/bsmpt.svg)](https://github.com/phbasler/BSMPT/blob/master/LICENSE.md)
@@ -48,19 +49,17 @@ The code is structured such that users can add their own models.
 The program package can be downloaded at:
 https://github.com/phbasler/BSMPT
 
-The documentation of the code is provided at [https://phbasler.github.io/BSMPT/documentation][DoxygenLink].
+The documentation of the code is provided at [https://phbasler.github.io/BSMPT/sphinx][SphinxLink].
 
 Sample input and output files are provided in the directory 'example'.
 
-Modifications and corrected bugs are reported in the file 'Changelog.md'.
-
 
 
 For additional information, comments, complaints or suggestions open a corresponding [issue](https://github.com/phbasler/BSMPT/issues) or start a [discussion](https://github.com/phbasler/BSMPT/discussions). For non-public matters please send an e-mail to [email protected].
 
 ---
 
-### Citation:
+## Citation:
 If you use this program for your work, please cite 
 
   - [1803.02846](https://arxiv.org/abs/1803.02846)
@@ -120,96 +119,5 @@ Code from the following repositories is used in BSMPT:
 - [`ttk592::spline`](https://github.com/ttk592/spline) by Tino Kluge, a C++ cubic spline interpolation library 
 - [`AsciiPlotter`](https://github.com/joehood/asciiplotter) by Joe Hood, for ASCII plots in the terminal 
 
----
-
-## How to add a new model:
-
-To add a new model, you have to modify/create five files (for further details, also consult the manual):
-
-1. Go to `include/BSMPT/models` and copy `ClassTemplate.h` to `YourModel.h`. Adjust the name of the class `Class_Template` to `Class_YourModel`.
-
-2. Go to `src/models` and copy `ClassTemplate.cpp` to `YourModel.cpp`, and again change `Class_Template` to `Class_YourModel`. Also, follow the instructions in this file and in the manual to set up your new model. 
-
-3. For your model to compile, you have to open `src/models/CMakeLists.txt` and add `${header_path}/YourModel.h` as well as `YourModel.cpp` to the listed headers and source files.
-
-4. In `include/BSMPT/models/IncludeAllModels.h` you need to add a new entry in the `enum class ModelIDs` above the `stop` entry which is different from the already defined `ModelIDs`, e.g. `YourModel`. Additionally, you have to create a new entry in the `const std::unordered_map<std::string, ModelIDs> ModelNames` map in the same file and add a new line with `{"YourModelName",ModelIDs::YourModel}`.
-
-5. In `src/models/IncludeAllModels.cpp` you have to add `#include <BSMPT/models/YourModel.h>` to the include list. Also, to be able to call your model, you have to extend the `FChoose` function. For this you add a new case to the switch statement, which reads
-
-        case ModelIDs::YourModel: return std::make_unique<Class_YourModel>(); break;
-
-### Generate the C++ code for a model
-We provide currently two methods to generate the tensors and calculate the counter terms for a new model.
-
-1. At `tools/ModelGeneration/Maple` we provide the maple Worksheet `CreateModel.mw` which you can use to implement your model and get the tensors.
-2. At `tools/ModelGeneration/sympy` we provide a setup using only `python3` with `sympy` (at least version 1.10!, if your packet manager only has an older installed, e.g. ubuntu 20.04 only has v1.6, then you have to install v1.10 or up with pip). Here we provide two examples, `SM.py` and `G2HDM.py` (generic 2HDM) which both use the `ModelGenerator.py` module to calculate the tensors and CT. You can get the CT using `python3 SM.py --show ct` and the tensors by calling `python3 SM.py --show tensors`. If your counterterms don't have a unique solution, then the solution space will be shown to you and you have to add additional equations until you have a unique solution (e.g. in the G2HDM example).
-3. To show the simplified tree-level and counterterm potentials, you can use `python3 SM.py --show treeSimpl` and `python3 SM.py --show CTSimpl`.
-
-
-
-You can use the Test executable to detect possible errors in your implementation. If the Test executable does not show you an error, but something is still wrong, contact us at [email protected]
-
-Also contact us if you have a custom model for BSMPT v1.x and you have trouble converting it to the new notation.
-
-## Executables
-BSMPT provides multiple executables. Here we give a quick overview of them. 
-Every executable can be called with the `--help` option to see how it can be run and to get an overview of all its required and optional arguments.
-Also, consult the manuals ([BSMPTv1](https://arxiv.org/abs/1803.02846), [BSMPTv2](https://arxiv.org/abs/2007.01725), [BSMPTv3](https://arxiv.org/abs/24XX.XXXXX])) for more details on the executables and their input parameters.
-
-Note, that every executable has the option to set the `--json=/path/to/your/file.json` which contains a json string with the parameters you can set through the CLI. This can be useful if you want to store the parameters you used for a given call. Please beware that all paths in the json file are considered relative to the current working directory and not to the location of the json file. Examples can be found in `example/JSON`. If you want to be sure to have the correct output file we recommend using absolute paths.
-
-
-In BSMPTv3, the following four executables are added:
-
-
-### MinimaTracer
-MinimaTracer tracks temperature-dependent local minima in a user-defined temperature interval.
-
-### CalcTemps
-CalcTemps identifies regions of coexisting minima, calculates the bounce solutions and characteristic temperature scales (critical, nucleation, percolation and completion temperature) of first-order phase transitions. Based on that, we report a transition history for the point.
-
-### CalcGW
-CalcGW expands CalcTemps by the additional calculation of the gravitational waves spectra sourced by first-order phase transitions.
-
-### PotPlotter
-PotPlotter calculates user-defined data grids that can be used for the visualization of multi-dimensional potential contours.
-
-
-The following executables were released with BSMPTv1 and BSMPTv2:
-
-
-### Test
-Test checks the model implementation for a provided parameter point. Some of the performed tests are e.g.: matching fermion masses and tree-level electroweak minimum with SM, tadpole relations, matching scalar masses between tree-level and NLO and symmetries of the coupling-tensors. The number of passed/failed tests is reported.
-
-### BSMPT
-BSMPT calculates the strength of a single-step electroweak phase transition (EWPT), defined as the ratio of the vacuum expectation value (VEV) at the critical temperature \f$v_c\f$ over the critical temperature \f$T_c\f$, based on finding a discontinuity in the electroweak VEV of the temperature-dependent global minimum.
-
-### CalcCT
-CalcCT calculates the (finite) counterterms for the 'on-shell' renormalization scheme.
-
-### NLOVEV
-NLOVEV calculates the zero-temperature VEV at one-loop order. This can be used to investigate the vacuum stability of the model.
-
-### VEVEVO
-VEVEVO calculates the evolution of the global minimum of a given point in a user-specified temperature range.
-
-### TripleHiggsCouplingNLO
-TripleHiggsCouplingNLO calculates the trilinear Higgs self-couplings at NLO at zero temperature.
-
-### CalculateEWBG
-CalculateEWBG calculates the difference between baryons and anti-baryons
-normalized to the photon density generated through the EWPT.
-Please beware that this is only tested for the C2HDM so far and the general
-implementation is future work.
-
-### PlotEWBG_vw
-PlotEWBG_vw varies the wall velocity of a given parameter point and
-calculates the baryon asymmetry for each velocity.
-
-### PlotEWBG_nL
-PlotEWBG_nL calculates the left-handed fermion density in front of the
-wall as a function of the distance to the bubble wall.
-
-
-
 [DoxygenLink]: https://phbasler.github.io/BSMPT/documentation
+[SphinxLink]: https://phbasler.github.io/BSMPT/sphinx

docs/_static/custom.css

@@ -0,0 +1,45 @@
+table.docutils td {
+    word-wrap: break-word;
+    white-space: normal;
+}
+
+body {
+    --themecolor: #fc9403;
+}
+
+.wy-side-nav-search {
+    background-color: var(--themecolor);
+}
+
+.wy-nav-top {
+    background-color: var(--themecolor);
+}
+
+.wy-menu-vertical a:hover {
+    background-color: var(--themecolor) !important;
+}
+
+/* Change sidebar section header color */
+.wy-nav-side .wy-menu-vertical a:hover {
+    background-color: var(--themecolor) !important;
+    /* Background color */
+    color: #ffffff !important;
+}
+
+.wy-menu-vertical p.caption {
+    color: #d95555;
+}
+
+a {
+    color: var(--themecolor);
+}
+
+/* Hover effect for links in the main content */
+.rst-content a:hover {
+    color: #e97502 !important;
+}
+
+.rst-content a:visited {
+    color: #d95555 !important;
+    /* Change visited link color */
+}

docs/build_sphinx.py

@@ -0,0 +1,58 @@
+import os
+import sys
+from sphinx.cmd.build import main as sphinx_main
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python build.py /path/to/xml [sphinx options]") 
+        sys.exit(1)
+    # Default values for Sphinx options
+
+    # Get the directory where the script is located 
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    defaults = {
+        'builder': 'html',  # Default builder
+        'config':  script_dir,  # Default configuration directory
+        'source': script_dir,  # Default source directory
+        'build': os.path.join(script_dir,"_build")  # Default build directory
+    }
+
+    # Convert default XML directory to an absolute path
+    xml_dir = os.path.abspath(sys.argv[1])
+    os.environ['XML_DIR'] = xml_dir
+
+    # Collect command-line arguments
+    cli_args = sys.argv[2:]
+
+    # Update defaults with command-line arguments if provided
+    if '-b' in cli_args:
+        defaults['builder'] = cli_args[cli_args.index('-b') + 1]
+    if '-c' in cli_args:
+        defaults['config'] = cli_args[cli_args.index('-c') + 1]
+    if len(cli_args) > 0:
+        defaults['source'] = cli_args[0]
+    if len(cli_args) > 1:
+        defaults['build'] = cli_args[1]
+
+     # Convert source and build paths to absolute paths 
+    defaults['config'] = os.path.abspath(defaults['config']) 
+    defaults['source'] = os.path.abspath(defaults['source']) 
+    defaults['build'] = os.path.abspath(defaults['build'])
+
+    # Construct the Sphinx command
+    sphinx_cmd = [
+        # 'sphinx-build', 
+        '-b', defaults['builder'], 
+        '-c', defaults['config'],
+        defaults['source'],
+        defaults['build']
+    ]
+
+    print(sphinx_cmd)
+
+    # Run Sphinx build with the constructed command
+    sphinx_main(sphinx_cmd)
+
+if __name__ == "__main__":
+    main()

docs/code.rst

@@ -0,0 +1,9 @@
+.. _code_page:
+
+Code Structure
+==============
+
+.. doxygenindex::
+   :project: BSMPT
+   :allow-dot-graphs:
+