Commit 833fe8a0 authored by Sebastian Müller's avatar Sebastian Müller 🐈
Browse files

Merge branch 'v0.1.1_release' into 'master'

v0.1.1 Release

See merge request !34
parents aa72cc50 d5cec9af
Pipeline #50531 passed with stages
in 33 minutes and 20 seconds
# ignore FORCES specific files
html
latex
doxygen_warn.txt
forces_env/
# Created by .ignore support plugin (hsz.mobi)
### Fortran template
# Prerequisites
......
......@@ -4,17 +4,14 @@
# enabled = true
# This will prevent git clone conflicts for jobs ran in parallel
variables:
GIT_DEPTH: 10
stages:
- info
- test
- deploy
workflow:
rules:
- if: $CI_COMMIT_REF_NAME =~ /-wip$/
when: never
- when: always
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME/$CI_CONCURRENT_ID
MAKE_FLAGS: -j 4
......@@ -39,7 +36,7 @@ documentation:
stage: test
variables:
GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_RUNNER_SHORT_TOKEN/$CI_PROJECT_PATH/$CI_COMMIT_REF_NAME/$CI_JOB_NAME
GIT_FETCH_EXTRA_FLAGS: --all --prune --quiet
GIT_FETCH_EXTRA_FLAGS: --all --no-tags --prune --quiet
script:
- module load foss/2019b
- module load texlive/2019
......@@ -62,6 +59,7 @@ documentation:
- cp refman.pdf ../html/forces_doc.pdf
- cp refman.pdf ../forces_doc_mas.pdf
- cd .. && mv html html_mas
- mv doxygen_warn.txt doxygen_warn_mas.txt
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
......@@ -79,6 +77,7 @@ documentation:
# how the job build directory is erected
.setup_build: &setup_build_dir
- rm -rf $BUILD_DIR
- mkdir -p $BUILD_DIR
- cd $BUILD_DIR
......@@ -92,7 +91,7 @@ documentation:
# make coverage command
.make_coverage: &make_coverage
- make $MAKE_FLAGS FORCES_coverage_CI
- make $MAKE_FLAGS coverage
# cleanup after scripts
.cleanup: &cleanup
......@@ -112,7 +111,8 @@ documentation:
# coverage variables
.coverage_vars: &coverage_vars
CMAKE_FLAGS: '$CMAKE_FLAGS -DBUILD_TESTING=ON -DCMAKE_WITH_COVERAGE=ON'
BUILD_DIR: build_debug
CMAKE_FLAGS: '$CMAKE_FLAGS -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_WITH_COVERAGE=ON'
# #################
# ### TEMPLATES ###
......@@ -134,20 +134,19 @@ documentation:
- $BUILD_DIR/Testing/Temporary
# template for coverage jobs
# .coverage_template: &coverage_template
# stage: test
# script:
# - source $MODULE_LOAD_SCRIPT
# - *setup_build_dir
# - cmake $CMAKE_FLAGS ..
# - *make
# - *make_coverage
# - *cleanup
# artifacts:
# when: always
# paths:
# - $BUILD_DIR/FORCES_coverage_CI.info
# - $BUILD_DIR/FORCES_coverage_CI
.coverage_template: &coverage_template
stage: test
script:
- source $MODULE_LOAD_SCRIPT
- *setup_build_dir
- cmake $CMAKE_FLAGS ..
- *make
- *make_coverage
- *cleanup
artifacts:
when: always
paths:
- $BUILD_DIR/coverage
# ##################
# ### BUILD JOBS ###
......@@ -249,14 +248,13 @@ test-intel19MPI-release:
CMAKE_FLAGS: '-DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Release'
<<: *test_template
# Coverage fails due to a gcov complication
# coverage-gcc73:
# variables:
# <<: *debug_vars
# <<: *coverage_vars
# MODULE_LOAD_SCRIPT: hpc-module-loads/eve.gfortran73MPI
# CMAKE_FLAGS: '-DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_WITH_COVERAGE=ON'
# <<: *coverage_template
coverage:
variables:
<<: *debug_vars
<<: *coverage_vars
MODULE_LOAD_SCRIPT: hpc-module-loads/eve.gfortran83MPI
CMAKE_FLAGS: '-DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_WITH_COVERAGE=ON'
<<: *coverage_template
# ###################
# ### DEPLOY JOBS ###
......@@ -270,6 +268,8 @@ pages:
needs:
- job: documentation
artifacts: true
- job: coverage
artifacts: true
script:
# create public dir (remove if already present)
- test -d public && rm -rf public
......@@ -282,6 +282,9 @@ pages:
- cp html_dev/* public/latest/ -R
# create an index.html that redirects to the master documentation (in master folder)
- cp doc/html_files/index.html public/
# create the coverage site
- mkdir -p public/coverage
- cp build_debug/coverage/* public/coverage/ -R
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
......
......@@ -19,15 +19,37 @@ project(FORCES
HOMEPAGE_URL "https://git.ufz.de/chs/forces/"
LANGUAGES Fortran
)
set (LIB_NAME forces)
# add full version and date to pre-processor flags (qoutes need in before hand)
add_compile_definitions(FORCESVERSION='${FORCES_VER_DEV}' FORCESDATE='${FORCES_DATE}')
# library module specific settings
add_subdirectory(./src)
# automatically enables testing
# prepare testing
option(BUILD_TESTING "Build with (pfUnit) tests." OFF)
include(CTest)
set(BUILD_FORCES_TESTS OFF)
if((CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME OR ${LIB_NAME}_BUILD_TESTING) AND BUILD_TESTING)
set(BUILD_FORCES_TESTS ON)
endif()
include(CTest)
# prepare coverage
if(CMAKE_Fortran_COMPILER_ID MATCHES "GNU" AND CMAKE_WITH_COVERAGE AND BUILD_FORCES_TESTS)
include(CodeCoverage)
append_coverage_compiler_flags()
SETUP_TARGET_FOR_COVERAGE_LCOV(
NAME coverage
EXECUTABLE ctest
DEPENDENCIES ${LIB_NAME}
EXCLUDE "src/pf_tests/*" "src/tests/*" "${CMAKE_CURRENT_BINARY_DIR}/*"
LCOV_ARGS --no-external
GENHTML_ARGS -t "${LIB_NAME} coverage" --html-prolog ../doc/html_files/cov_header.prolog
)
endif()
# library module specific settings (defined after coverage definition)
add_subdirectory(./src)
if(BUILD_FORCES_TESTS)
# add test directories (defined after coverage definition)
add_subdirectory(./src/pf_tests)
add_subdirectory(./src/tests)
endif()
# FORCES - FORtran library for Computational Environmental Systems
# FORtran library for Computational Environmental Systems
<div align="center">
<img src="https://git.ufz.de/chs/logos/-/raw/master/Forces.png" alt="Forces-LOGO" width="251px" style="width:251px;"/>
......@@ -6,10 +6,10 @@
This is the FORTRAN library of the
Department Computational Hydrosystems
Helmholtz Centre for Environmental Research - UFZ
Permoserstr. 15
04318 Leipzig, Germany
> Department Computational Hydrosystems<br/>
> Helmholtz Centre for Environmental Research - UFZ<br/>
> Permoserstr. 15<br/>
> 04318 Leipzig, Germany
It is a lightweight fork of the `jams_fortran` library maintained by Matthias Cuntz et al: https://github.com/mcuntz/jams_fortran
......@@ -27,6 +27,17 @@ It is recommended to have a clean installation at a custom location
for a C compiler, a Fortran compiler, the NetCDF C library and the
NetCDF Fortran library with consistent compilers.
You can also use a conda environment to get all dependencies:
```bash
conda create -y --prefix ./forces_env
conda activate ./forces_env
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install -y cmake make fortran-compiler netcdf-fortran fypp
cmake -DCMAKE_BUILD_TYPE=Release -B build -S .
cmake --build build --parallel
```
## License
......@@ -36,3 +47,15 @@ The routines is released under the GNU Lesser General Public License. The follow
The UFZ Fortran library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
FORCES is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
### Doxygen Awesome
Doxygen Awesome is included as subrepo under `doc/doxygen-awesome-css/` from https://github.com/jothepro/doxygen-awesome-css. It is released under the MIT license.
### Cmake Fortran Scripts
The CHS Cmake Fortran Scripts repository is included as subrepo under `cmake/` from https://git.ufz.de/chs/cmake-fortran-scripts. It is released under the GNU LGPLv3 license.
### HPC Fortran Module Loads
The CHS HPC Fortran Module Loads repository is included as subrepo under `hpc-module-loads/` from https://git.ufz.de/chs/HPC-Fortran-module-loads. It is released under the GNU LGPLv3 license.
......@@ -5,8 +5,8 @@
;
[subrepo]
remote = https://git.ufz.de/chs/cmake-fortran-scripts.git
branch = v1.3
commit = 65c29b824958243b668ff1a7480a343509226725
parent = 760ac2af99a2dc57bb35cf4c0dc0d25819adb2fc
branch = v1.5
commit = c532558873f4cd5d640d10327bfddf63a4e8ca5a
parent = 74455c067272384bbf2b359735d37361b83d3613
method = merge
cmdver = 0.4.3
......@@ -56,7 +56,7 @@ Copied from [NOAA-EMC/CMakeModules](https://github.com/NOAA-EMC/CMakeModules/blo
Can be used like:
```cmake
find_package(NetCDF COMPONENTS Fortran)
target_link_libraries(<lib_name> PUBLIC NetCDF::NetCDF_Fortran)
target_link_libraries(<target> PUBLIC NetCDF::NetCDF_Fortran)
```
### `version.cmake`
......@@ -68,6 +68,24 @@ include(version)
get_version(PROJECT_VER PROJECT_VER_DEV PROJECT_DATE)
```
### `CPM.cmake` (v0.34.0)
CPM.cmake is a CMake script that adds dependency management capabilities to CMake.
It's built as a thin wrapper around CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)
module that adds version control, caching, a simple API [and more](#comparison-to-pure-fetchcontent--externalproject).
Copied from: https://github.com/cpm-cmake/CPM.cmake
Can be used like:
```cmake
include(CPM)
CPMAddPackage(
NAME forces
GIT_REPOSITORY https://git.ufz.de/chs/forces.git
GIT_TAG v0.1.0
)
target_link_libraries(<project> PUBLIC forces)
```
## Cmake Cache Files
Cache files provide templates for specific cmake setups.
......
This diff is collapsed.
......@@ -183,7 +183,7 @@ else()
endif()
if(NetCDF_PARALLEL)
find_package(MPI REQUIRED)
find_package(MPI)
endif()
## Find libraries for each component
......@@ -344,4 +344,4 @@ foreach( _prefix NetCDF NetCDF4 NETCDF NETCDF4 ${CMAKE_FIND_PACKAGE_NAME} )
set( ${_prefix}_${_COMP}_INCLUDE_DIRS ${NetCDF_${_comp}_INCLUDE_DIRS} )
set( ${_prefix}_${_arg_comp}_INCLUDE_DIRS ${NetCDF_${_comp}_INCLUDE_DIRS} )
endforeach()
endforeach()
\ No newline at end of file
endforeach()
name: publish
on:
release:
types: [published]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: set version
run: echo "PROJECT_NUMBER = `git describe --tags`" >> Doxyfile
- name: Generate Documentation
uses: mattnotmitt/doxygen-action@v1
- name: Publish generated content to GitHub Pages
uses: tsunematsu21/actions-publish-gh-pages@v1.0.1
with:
dir: docs/html
branch: gh-pages
token: ${{ secrets.ACCESS_TOKEN }}
\ No newline at end of file
docs/html
.DS_Store
.idea
\ No newline at end of file
; DO NOT EDIT (unless you know what you are doing)
;
; This subdirectory is a git "subrepo", and this file is maintained by the
; git-subrepo command. See https://github.com/git-commands/git-subrepo#readme
;
[subrepo]
remote = https://github.com/jothepro/doxygen-awesome-css.git
branch = v1.5.0
commit = 9380569e8aea36374d848c8a43c6f9c6343d9bc0
parent = dbf958ef712fcc1597e2e77e3a4e6eb38a0761e0
method = merge
cmdver = 0.4.3
This diff is collapsed.
MIT License
Copyright (c) 2021 jothepro
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Doxygen Awesome
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/jothepro/doxygen-awesome-css)](https://github.com/jothepro/doxygen-awesome-css/releases/latest)
[![GitHub](https://img.shields.io/github/license/jothepro/doxygen-awesome-css)](https://github.com/jothepro/doxygen-awesome-css/blob/main/LICENSE)
<div style="margin: -1% -4.4%;">
[![Screenshot of Doxygen Awesome CSS](img/screenshot.png)](https://jothepro.github.io/doxygen-awesome-css/)
</div>
**Doxygen Awesome** is a custom **CSS theme for doxygen** html-documentation with lots of customization parameters.
## Motivation
I really like how the doxygen html-documentation is structured! But IMHO it looks a bit outdated.
This theme is an attemt to update the visuals of doxygen without changing it's overall layout too much.
## Features
- 🌈 Clean, modern design
- 🚀 Heavily customizable by adjusting CSS-variables
- 🧩 No changes to the HTML structure of Doxygen required
- 📱 Improved mobile usability
- 🌘 Dark mode support!
- 🥇 Works best with **doxygen 1.9.1**
## Installation
Copy the `css` files from this repository into your project or add this repository as submodule and check out the latest release:
```bash
git submodule add https://github.com/jothepro/doxygen-awesome-css.git
cd doxygen-awesome-css
git checkout v1.5.0
```
Then make the option `HTML_EXTRA_STYLESHEET` in your Doxyfile point to the `css` files:
```
# Doxyfile
# ...
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
```
### Variants
There is two variants of the theme.
![theme variations](img/theme-variations.drawio.svg)
1. **Base theme**:
```
# Doxyfile
GENERATE_TREEVIEW = YES # optional. Also works without treeview
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
```
2. **Sidebar-only theme** (experimental):
```
# Doxyfile
GENERATE_TREEVIEW = YES # required!
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css doxygen-awesome-css/doxygen-awesome-sidebar-only.css
```
### Dark Mode Toggle (Experimental)
The theme comes with an experimental feature that adds a button to enable and disable the dark theme variant manually.
It requires customizations in both the header & footer html template.
```bash
# Create default header & footer templates
doxygen -w html header.html footer.html
```
```
# Doxyfile
# Include the required Javascript
HTML_EXTRA_FILES = doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
# Add the additional CSS. This is ONLY required for the sidebar-only theme variant!
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
doxygen-awesome-css/doxygen-awesome-sidebar-only.css \
doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css
# set custom header & footer templates
HTML_HEADER = header.html
HTML_FOOTER = footer.html
```
```html
<!-- header.html -->
<html>
<head>
<!-- import the script somewhere in the head -->
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
</head>
<body>
<!-- footer.html -->
</body>
<!-- add the button to toggle the theme -->
<script>
$(document).ready(function(){
toggleButton = document.createElement('doxygen-awesome-dark-mode-toggle')
toggleButton.title = "Toggle Light/Dark Mode"
document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
})
</script>
</html>
```
## Examples
- Sidebar-Only theme: [Documentation of this repository](https://jothepro.github.io/doxygen-awesome-css/)
- Base theme: [libsl3](https://a4z.github.io/libsl3/)
## Configuration
### CSS Variables
This theme is highly customizable because a lot of things are parameterized with CSS variables. The following
list of parameters is not complete! You can easily modify any variable with the developer tools of your browser to find
out what it does.
To customize the existing theme, add your own `custom.css` and overwrite the variables there:
```
HTML_EXTRA_STYLESHEET = doxygen-awesome-theme/doxygen-awesome.css custom.css
```
```css
/* custom.css */
html {
/* define light-mode variable overrides here */
}
@media (prefers-color-scheme: dark) {
html:not(.light-mode) {
/* define dark-mode variable overrides here if you DON'T use doxygen-awesome-darkmode-toggle.js */
}
}
html.dark-mode {
/* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */
}
```
| Parameter | Default (Light) | Default (Dark) |
| :-------------------------------- | :---------------------------------------------------------- | ----------------------------------------------------------- |
| **Color Scheme**:<br>primary theme color. This will affect the entire websites color scheme: links, arrows, labels, ... |||
| `--primary-color` | <span style="background:#1779c4;color:white">#1779c4</span> | <span style="background:#1982d2;color:white">#1982d2</span> |
| `--primary-dark-color` | <span style="background:#00559f;color:white">#00559f</span> | <span style="background:#5ca8e2;color:white">#5ca8e2</span> |
| `--primary-light-color` | <span style="background:#7aabd6;color:black">#7aabd6</span> | <span style="background:#4779ac;color:white">#4779ac</span> |
| `--primary-lighter-color` | <span style="background:#cae1f1;color:black">#cae1f1</span> | <span style="background:#191e21;color:white">#191e21</span> |
| `--primary-lightest-color` | <span style="background:#e9f1f8;color:black">#e9f1f8</span> | <span style="background:#191a1c;color:white">#191a1c</span> |
| **Spacing:**<br>default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. |||
| `--spacing-small` | `5px` | |
| `--spacing-medium` | `10px` | |
| `--spacing-large` | `16px` | |
| **Border Radius**:<br>border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... |||
| `--border-radius-small` | `4px` | |
| `--border-radius-medium` | `6px` | |
| `--border-radius-large` | `8px` | |
| **Content Width**:<br>The content is centered and constraint in it's width. To make the content fill the whole page, set the following variable to `auto`. |||
| `--content-maxwidth` | `900px` | |
| **Code Fragment Colors**:<br>Color-Scheme of multiline codeblocks |||
| `--fragment-background` | <span style="background:#282c34;color:white">#282c34</span> | |
| `--fragment-foreground` | <span style="background:#fff;wolor:black">#fff</span> | |
| **Arrow Opacity**:<br>By default the arrows in the sidebar are only visible on hover. You can override this behaviour so they are visible all the time. |||
| `--side-nav-arrow-opacity` | `0` | |
| `--side-nav-arrow-hover-opacity` | `0.9` | |
| **Darkmode Toggle Icon**:<br>If you have enabled the darkmode toggle button, you can define the icon that is shown for the current mode. |||
| `--darkmode-toggle-button-icon` | ☀️ | 🌛 |
| ...and many more |||
If you miss a configuration option or find a bug, please consider [opening an issue](https://github.com/jothepro/doxygen-awesome-css/issues)!
### Doxygen generator
The theme overrides most colors with the `--primary-color-*` variables.
But there is a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with
the rest, it is recommended to adjust the [doxygen color settings](https://www.doxygen.nl/manual/customize.html#minor_tweaks_colors)
to something that matches the chosen color-scheme.
For the default color-scheme, these values work out quite well:
```
# Doxyfile
HTML_COLORSTYLE_HUE = 209
HTML_COLORSTYLE_SAT = 255
HTML_COLORSTYLE_GAMMA = 113
```
## Browser support
Tested with
- Chrome 91, Chrome 91 for Android, Chrome 87 for iOS
- Safari 14, Safari for iOS 14
- Firefox 89, Firefox Daylight 89 for Android, Firefox Daylight 33 for iOS
## Tips & Tricks
### Class Diagrams with Graphviz
To get the best looking class diagrams for your documentation, generate them with Graphviz as vector graphics with transparent background:
```
# Doxyfile
HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
DOT_TRANSPARENT = YES
```
### Share your own theme customizations
If you customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can to this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13).
I am always curious to learn about how you made the theme look even better!
## Credits
This theme is heavily inspired by the beautiful [vuepress](https://vuepress.vuejs.org/) static site generator default theme!
.github-corner svg {
fill: var(--primary-light-color);
color: var(--page-background-color);
width: 72px;
height: 72px;
}
@media screen and (max-width: 767px) {
.github-corner svg {
width: 55px;
height: 55px;
}
#projectnumber {
margin-right: 22px;
}
}
<!-- HTML footer for doxygen 1.9.1-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
$navpath
<li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
</ul>
</div>
<!--END GENERATE_TREEVIEW-->