Merge branch 'improvement.github.pages' into 'main'

GitHub Pages

See merge request flexi/codes/relexi!18

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: documentation
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -r requirements.txt
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: cd docs/ && bash build_docs.sh
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -2,6 +2,8 @@
 
 [![license](https://img.shields.io/github/license/flexi-framework/relexi.svg?maxAge=2592000 "GPL-3.0 License")](LICENSE.md)
 [![doi](https://img.shields.io/badge/DOI-10.1016/j.simpa.2022.100422-blue "DOI")](https://doi.org/10.1016/j.simpa.2022.100422)
+[![docsbuild](https://img.shields.io/github/deployments/flexi-framework/relexi/github-pages?label=docs%20build)](https://flexi-framework.github.io/relexi/relexi.html)
+[![userguide](https://img.shields.io/badge/Documentation-silver "Documentation")](https://flexi-framework.github.io/relexi/relexi.html)
 
 # About Relexi
 Relexi is a Reinforcement Learning (RL) framework developed for the high-order HPC flow solver [FLEXI][flexi].
@@ -17,24 +19,6 @@ For details on its scaling behavior, suitability for HPC and for use cases, plea
 This is a scientific project.
 If you use Relexi or find it helpful, please cite the project using a suitable reference from the list above referring to either the general Relexi project, its HPC aspects or its application for scientific modeling tasks, respectively.
 
-# Documentation
-The documentation of Relexi is built via `pdoc`, which can be installed via
-```bash
-pip install pdoc
-```
-Next, change into the `docs` folder and build the documentation via
-```bash
-cd docs
-bash build_docs.sh
-```
-Open the resulting `relexi.html` with your browser.
-
-# Testing
-A suite of unit tests is implemented for Relexi using the `pytest` testing environment. To run the tests, simply execute in the root directory
-```bash
-pytest
-```
-
 # Installation
 The following quick start details a standard installation of the Relexi framework.
 
@@ -45,9 +29,9 @@ The main dependencies of Relexi are listed in the following with their supported
 | Package          | Version         | Note                                    |
 |:-----------------|----------------:|:----------------------------------------|
 | Python           |          ≥3.9   |                                         |
-| TensorFlow       |   2.9.0 - 2.15.1|                                         |
+| TensorFlow       |     2.9 - 2.15  |                                         |
 | TF-Agents        |          ≥0.13  |                                         |
-| SmartSim         |   0.4.0 - 0.6.2 |                                         |
+| SmartSim         |     0.4 - 0.6   |                                         |
 | SmartRedis       |          ≥0.4.1 |                                         |
 | CMake            |          ≥3.0   |                                         |
 | Make             |          ≥4.0   |                                         |
@@ -63,30 +47,23 @@ For convenience, save the current directory with
 ```bash
 ROOTDIR=$(pwd)
 ```
-It is highly recommended to use some form of virtual environment for the installation. You can use any tool you like, we use `virtualenv` which can be installed with
+It is highly recommended to use some form of virtual environment for the installation.
+You can use create and activate a new environment using `virtualenv` via
 ```bash
 python3 -m pip install virtualenv
-```
-Create and activate a new environment with
-```bash
 python3 -m virtualenv env_relexi
 source env_relexi/bin/activate
 ```
 Install the necessary dependencies
 ```bash
-python3 -m pip install tensorflow smartredis cmake tf-agents pyyaml matplotlib
+python3 -m pip install -r requirements.txt
 ```
 
 ### Install SmartSim
-Install SmartSim in a supported version ranging from `0.4.0` to `0.6.2`. The following commands install the latest supported version.
+After installing the `smartsim` package via pip, it has to be installed with its dependencies via the `smart` commandline tool:
 ```bash
-pip install smartsim==0.6.2
-smart clobber
-smart clean
-smart build --no_tf --no_pt -v
-SMARTSIM_DIR=$(smart site)
-export PATH=$PATH:$SMARTSIM_DIR/_core/bin
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${SMARTSIM_DIR}/_core/lib
+smart clobber && smart clean
+smart build --no_tf
 ```
 
 ### Install FLEXI
@@ -136,3 +113,22 @@ ssh -L 6006:127.0.0.1:6006 your_remote_server
 [nrg]:       https://numericsresearchgroup.org/index.html
 [flexi]:     https://numericsresearchgroup.org/flexi_index.html
 [userguide]: https://numericsresearchgroup.org/userguide/userguide.pdf
+
+# Documentation
+The documentation of Relexi can be found [here](https://flexi-framework.github.io/relexi/relexi.html).
+It is built with `pdoc`, which can be installed via
+```bash
+pip install pdoc
+```
+with which the documentation can be built with
+```bash
+cd docs
+bash build_docs.sh
+```
+Open the resulting `relexi.html` with your browser.
+
+# Testing
+A suite of unit tests is implemented for Relexi using the `pytest` testing environment. To run the tests, simply execute in the root directory
+```bash
+pytest
+```

docs/build_docs.sh

@@ -1,2 +1,2 @@
-!/usr/bin/env bash
-pdoc -d google -o . ../src/relexi --logo "https://numericsresearchgroup.org/images/icons/relexi.svg" --favicon "https://numericsresearchgroup.org/images/icons/icon.png"
+#!/usr/bin/env bash
+pdoc -t . -d google -o . ../src/relexi --logo "https://numericsresearchgroup.org/images/icons/relexi.svg" --favicon "https://numericsresearchgroup.org/images/icons/relexi_logo.svg"

docs/syntax-highlighting.css

@@ -0,0 +1,83 @@
+/* Example dark mode color scheme from the pdoc repository:
+ * https://github.com/mitmproxy/pdoc/blob/main/examples/dark-mode/syntax-highlighting.css */
+
+/* monokai color scheme, see pdoc/template/README.md */
+pre { line-height: 125%; }
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; }
+.pdoc-code .hll { background-color: #49483e }
+.pdoc-code { background: #272822; color: #f8f8f2 }
+.pdoc-code .c { color: #75715e } /* Comment */
+.pdoc-code .err { color: #960050; background-color: #1e0010 } /* Error */
+.pdoc-code .esc { color: #f8f8f2 } /* Escape */
+.pdoc-code .g { color: #f8f8f2 } /* Generic */
+.pdoc-code .k { color: #66d9ef } /* Keyword */
+.pdoc-code .l { color: #ae81ff } /* Literal */
+.pdoc-code .n { color: #f8f8f2 } /* Name */
+.pdoc-code .o { color: #f92672 } /* Operator */
+.pdoc-code .x { color: #f8f8f2 } /* Other */
+.pdoc-code .p { color: #f8f8f2 } /* Punctuation */
+.pdoc-code .ch { color: #75715e } /* Comment.Hashbang */
+.pdoc-code .cm { color: #75715e } /* Comment.Multiline */
+.pdoc-code .cp { color: #75715e } /* Comment.Preproc */
+.pdoc-code .cpf { color: #75715e } /* Comment.PreprocFile */
+.pdoc-code .c1 { color: #75715e } /* Comment.Single */
+.pdoc-code .cs { color: #75715e } /* Comment.Special */
+.pdoc-code .gd { color: #f92672 } /* Generic.Deleted */
+.pdoc-code .ge { color: #f8f8f2; font-style: italic } /* Generic.Emph */
+.pdoc-code .gr { color: #f8f8f2 } /* Generic.Error */
+.pdoc-code .gh { color: #f8f8f2 } /* Generic.Heading */
+.pdoc-code .gi { color: #a6e22e } /* Generic.Inserted */
+.pdoc-code .go { color: #66d9ef } /* Generic.Output */
+.pdoc-code .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */
+.pdoc-code .gs { color: #f8f8f2; font-weight: bold } /* Generic.Strong */
+.pdoc-code .gu { color: #75715e } /* Generic.Subheading */
+.pdoc-code .gt { color: #f8f8f2 } /* Generic.Traceback */
+.pdoc-code .kc { color: #66d9ef } /* Keyword.Constant */
+.pdoc-code .kd { color: #66d9ef } /* Keyword.Declaration */
+.pdoc-code .kn { color: #f92672 } /* Keyword.Namespace */
+.pdoc-code .kp { color: #66d9ef } /* Keyword.Pseudo */
+.pdoc-code .kr { color: #66d9ef } /* Keyword.Reserved */
+.pdoc-code .kt { color: #66d9ef } /* Keyword.Type */
+.pdoc-code .ld { color: #e6db74 } /* Literal.Date */
+.pdoc-code .m { color: #ae81ff } /* Literal.Number */
+.pdoc-code .s { color: #e6db74 } /* Literal.String */
+.pdoc-code .na { color: #a6e22e } /* Name.Attribute */
+.pdoc-code .nb { color: #f8f8f2 } /* Name.Builtin */
+.pdoc-code .nc { color: #a6e22e } /* Name.Class */
+.pdoc-code .no { color: #66d9ef } /* Name.Constant */
+.pdoc-code .nd { color: #a6e22e } /* Name.Decorator */
+.pdoc-code .ni { color: #f8f8f2 } /* Name.Entity */
+.pdoc-code .ne { color: #a6e22e } /* Name.Exception */
+.pdoc-code .nf { color: #a6e22e } /* Name.Function */
+.pdoc-code .nl { color: #f8f8f2 } /* Name.Label */
+.pdoc-code .nn { color: #f8f8f2 } /* Name.Namespace */
+.pdoc-code .nx { color: #a6e22e } /* Name.Other */
+.pdoc-code .py { color: #f8f8f2 } /* Name.Property */
+.pdoc-code .nt { color: #f92672 } /* Name.Tag */
+.pdoc-code .nv { color: #f8f8f2 } /* Name.Variable */
+.pdoc-code .ow { color: #f92672 } /* Operator.Word */
+.pdoc-code .w { color: #f8f8f2 } /* Text.Whitespace */
+.pdoc-code .mb { color: #ae81ff } /* Literal.Number.Bin */
+.pdoc-code .mf { color: #ae81ff } /* Literal.Number.Float */
+.pdoc-code .mh { color: #ae81ff } /* Literal.Number.Hex */
+.pdoc-code .mi { color: #ae81ff } /* Literal.Number.Integer */
+.pdoc-code .mo { color: #ae81ff } /* Literal.Number.Oct */
+.pdoc-code .sa { color: #e6db74 } /* Literal.String.Affix */
+.pdoc-code .sb { color: #e6db74 } /* Literal.String.Backtick */
+.pdoc-code .sc { color: #e6db74 } /* Literal.String.Char */
+.pdoc-code .dl { color: #e6db74 } /* Literal.String.Delimiter */
+.pdoc-code .sd { color: #e6db74 } /* Literal.String.Doc */
+.pdoc-code .s2 { color: #e6db74 } /* Literal.String.Double */
+.pdoc-code .se { color: #ae81ff } /* Literal.String.Escape */
+.pdoc-code .sh { color: #e6db74 } /* Literal.String.Heredoc */
+.pdoc-code .si { color: #e6db74 } /* Literal.String.Interpol */
+.pdoc-code .sx { color: #e6db74 } /* Literal.String.Other */
+.pdoc-code .sr { color: #e6db74 } /* Literal.String.Regex */
+.pdoc-code .s1 { color: #e6db74 } /* Literal.String.Single */
+.pdoc-code .ss { color: #e6db74 } /* Literal.String.Symbol */
+.pdoc-code .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */
+.pdoc-code .fm { color: #a6e22e } /* Name.Function.Magic */
+.pdoc-code .vc { color: #f8f8f2 } /* Name.Variable.Class */
+.pdoc-code .vg { color: #f8f8f2 } /* Name.Variable.Global */
+.pdoc-code .vi { color: #f8f8f2 } /* Name.Variable.Instance */
+.pdoc-code .vm { color: #f8f8f2 } /* Name.Variable.Magic */

docs/theme.css

@@ -0,0 +1,23 @@
+/* Example dark mode color scheme from the pdoc repository:
+ * https://github.com/mitmproxy/pdoc/blob/main/examples/dark-mode/theme.css */
+
+:root {
+    --pdoc-background: #212529;
+}
+
+.pdoc {
+    --text: #f7f7f7;
+    --muted: #9d9d9d;
+    --link: #58a6ff;
+    --link-hover: #3989ff;
+    --code: #333;
+    --active: #555;
+
+    --accent: #343434;
+    --accent2: #555;
+
+    --nav-hover: rgba(0, 0, 0, 0.1);
+    --name: #77C1FF;
+    --def: #0cdd0c;
+    --annotation: #00c037;
+}

requirements.txt

@@ -0,0 +1,10 @@
+smartsim>=0.4,<0.7
+smartredis
+tensorflow>=2.9,<2.16
+tf-agents
+cmake
+pyyaml
+matplotlib
+pdoc
+pytest
+pytest-cov