diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..2605b5d3 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +# Reviewers for Dependabot PRs +build.gradle @sebastian-peter @danielfeismann @staudtMarius + +# Reviewers for CI/CD related PRs +.github/workflows/ @sebastian-peter @PhilippSchmelter diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 96d947ce..e7d753d5 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,8 +7,3 @@ updates: time: "04:00" open-pull-requests-limit: 10 target-branch: main - reviewers: - - ckittl - - johanneshiry - - t-ober - - sensarmad diff --git a/.gitignore b/.gitignore index 4a7315f3..11999b84 100644 --- a/.gitignore +++ b/.gitignore @@ -219,3 +219,11 @@ gradle-app.setting # Cache of project .gradletasknamecache + +# Read the docs integration +# Don't commit the virtual environment of python +**/venv +docs/readthedocs/build + +# Ignore output files +/output/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..47a63bab --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-24.04 + tools: + python: "3.13" + +# Configure python +python: + install: + - requirements: docs/readthedocs/requirements.txt + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/readthedocs/conf.py diff --git a/build.gradle b/build.gradle index 91f04acd..0e1b6bf2 100644 --- a/build.gradle +++ b/build.gradle @@ -14,7 +14,7 @@ plugins { ext { //version (changing these should be considered thoroughly!) - javaVersion = JavaVersion.VERSION_11 + javaVersion = JavaVersion.VERSION_17 tscfgVersion = '0.9.986' scriptsLocation = 'gradle' + File.separator + 'scripts' + File.separator //location of script } @@ -90,7 +90,7 @@ dependencies { testImplementation 'junit:junit:4.13.2' testImplementation 'cglib:cglib-nodep:3.3.0' // enables mocking of classes (in addition to interfaces) testImplementation 'org.mockito:mockito-core:3.11.2' // mocking framework - testImplementation 'org.spockframework:spock-core:2.0-M3-groovy-3.0' + testImplementation 'org.spockframework:spock-core:2.3-groovy-4.0' testImplementation 'org.objenesis:objenesis:3.2' // Mock creation with constructor parameters // config // @@ -99,16 +99,16 @@ dependencies { } -wrapper { - gradleVersion = '7.0' +tasks.withType(JavaCompile) { + options.encoding = 'UTF-8' } -tasks.withType(JavaCompile) { - options.encoding = 'UTF-8' +tasks.withType(Javadoc){ + options.encoding = 'UTF-8' } -task printVersion { - doLast { - println project.version - } +tasks.register("printVersion") { + doLast { + println project.version + } } diff --git a/docs/readthedocs/Makefile b/docs/readthedocs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/readthedocs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/readthedocs/_static/css/theme_override.css b/docs/readthedocs/_static/css/theme_override.css new file mode 100644 index 00000000..b76c7ef9 --- /dev/null +++ b/docs/readthedocs/_static/css/theme_override.css @@ -0,0 +1,13 @@ +/* Suppress spacing after multi-line entries in tables + * Inspired by this issue: https://github.com/readthedocs/sphinx_rtd_theme/issues/117 */ +.wy-table-responsive table td div.line-block { + margin-bottom: 0; + font-size: 90%; +} +.wy-table-responsive table th div.line-block { + margin-bottom: 0; + font-size: 90%; +} +.wy-table-responsive table th p { + margin-bottom: 0; +} diff --git a/docs/readthedocs/conf.py b/docs/readthedocs/conf.py new file mode 100644 index 00000000..3e1323ae --- /dev/null +++ b/docs/readthedocs/conf.py @@ -0,0 +1,73 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'OSMoGrid' +copyright = u'2021. TU Dortmund University, Institute of Energy Systems, Energy Efficiency and Energy Economics, Research group Distribution grid planning and operation ' +author = 'Johannes Hiry, Chris Kittl, Lars Lenssen, Thomas Oberließen, Sebastian Peter' + +# The full version, including alpha/beta/rc tags +version = '1.0' +release = '1.0.1-SNAPSHOT' + +pygments_style = 'tango' +add_function_parentheses = True +# Will point sphinx to use 'index.rst' as the master document +master_doc = 'index' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'myst_parser', + 'sphinx.ext.autosectionlabel', +] + +# Prefix all autogenerated labels wit the document to get unique labels (e.g. `index:Hello`) +autosectionlabel_prefix_document = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv'] + +source_encoding = 'utf-8-sig' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' +html_short_title = "OSMoGrid" +htmlhelp_basename = 'OSMoGrid-doc' +html_use_index = True +html_show_sourcelink = False + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +def setup(app): + app.add_css_file("css/theme_override.css") diff --git a/docs/readthedocs/index.rst b/docs/readthedocs/index.rst new file mode 100644 index 00000000..f95d40d3 --- /dev/null +++ b/docs/readthedocs/index.rst @@ -0,0 +1,19 @@ +.. OSMoGrid documentation master file, created by + sphinx-quickstart on Sun Nov 28 14:17:05 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to OSMoGrid's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/readthedocs/make.bat b/docs/readthedocs/make.bat new file mode 100644 index 00000000..8084272b --- /dev/null +++ b/docs/readthedocs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/readthedocs/requirements.txt b/docs/readthedocs/requirements.txt new file mode 100644 index 00000000..538bf233 --- /dev/null +++ b/docs/readthedocs/requirements.txt @@ -0,0 +1,3 @@ +myst-parser==4.0.1 +Sphinx==8.2.3 +sphinx-rtd-theme==3.0.2 diff --git a/gradle/scripts/documentation.gradle b/gradle/scripts/documentation.gradle index 0d9d1a8b..fa7303d6 100644 --- a/gradle/scripts/documentation.gradle +++ b/gradle/scripts/documentation.gradle @@ -9,23 +9,23 @@ def docBaseDirPath = project.projectDir.toString() + File.separator + project.do * Configuring the sphinx plugin */ sphinx { - description 'Generate high level HTML documentation output.' - group 'Documentation' + description 'Generate high level HTML documentation output.' + group 'Documentation' - sourceDirectory = "${docBaseDirPath}/readthedocs" - outputDirectory = "${project.buildDir}/docs/readthedocs" + sourceDirectory = "${docBaseDirPath}/readthedocs" + outputDirectory = layout.buildDirectory.dir("/docs/readthedocs") } /** * Task to generate the JavaDoc */ javadoc() { - description 'Generates java API doc at the correct place.' - group 'Documentation' + description 'Generates java API doc at the correct place.' + group 'Documentation' - source = sourceSets.main.allJava - destinationDir = file( docBaseDirPath + 'javadoc' ) - classpath = project.sourceSets.main.compileClasspath + source = sourceSets.main.allJava + destinationDir = file( docBaseDirPath + 'javadoc' ) + classpath = project.sourceSets.main.compileClasspath } /** @@ -34,27 +34,58 @@ javadoc() { * Important note: you have to install GraphViz Manually before being able to execute this task! -> https://graphviz.org */ task puml2png() { - description 'Converts plantUML diagrams to png files.' - group 'Documentation' - - doLast { - /* Get the PlantUML-jar or download it, if it is not available */ - def pumlJarFile = project.file("${project.buildDir}/plantuml.jar") - if (!pumlJarFile.exists() || !pumlJarFile.isFile()) { - download { - src 'https://downloads.sourceforge.net/project/plantuml/plantuml.jar' - dest buildDir - } - } - javaexec { - main = "-jar" - args = [ - "build/plantuml.jar", - "-psvg", - "-o", - "${docBaseDirPath}readthedocs/_static/figures/uml/", - "${docBaseDirPath}uml/**/*.puml" - ] - } - } + description 'Converts plantUML diagrams to png files.' + group 'Documentation' + + doLast { + /* Get the PlantUML-jar or download it, if it is not available */ + def pumlJarFile = layout.buildDirectory.file("plantuml.jar").get().asFile + if (!pumlJarFile.exists() || !pumlJarFile.isFile()) { + download.run { + src 'https://downloads.sourceforge.net/project/plantuml/plantuml.jar' + dest layout.buildDirectory.get() + } + } + javaexec { + main = "-jar" + args = [ + "build/plantuml.jar", + "-psvg", + "-o", + "${docBaseDirPath}readthedocs/_static/figures/puml/", + "${docBaseDirPath}puml/**/*.puml" + ] + } + } +} + +/** + * Converts the PlantUML diagrams to a svg file, so that those can be used in sphinx documentation + * + * Important note: you have to install GraphViz Manually before being able to execute this task! -> https://graphviz.org + */ +task puml2svg() { + description 'Converts plantUML diagrams to svg files.' + group 'Documentation' + + doLast { + /* Get the PlantUML-jar or download it, if it is not available */ + def pumlJarFile = layout.buildDirectory.file("plantuml.jar").get().asFile + if (!pumlJarFile.exists() || !pumlJarFile.isFile()) { + download.run { + src 'https://downloads.sourceforge.net/project/plantuml/plantuml.jar' + dest layout.buildDirectory.get() + } + } + javaexec { + main = "-jar" + args = [ + "build/plantuml.jar", + "-svg", + "-o", + "${docBaseDirPath}readthedocs/_static/figures/puml/", + "${docBaseDirPath}puml/**/*.puml" + ] + } + } } diff --git a/gradle/scripts/jacoco.gradle b/gradle/scripts/jacoco.gradle index 2736c423..acbe5aa3 100644 --- a/gradle/scripts/jacoco.gradle +++ b/gradle/scripts/jacoco.gradle @@ -4,16 +4,16 @@ // general configuration jacoco { toolVersion = "0.8.4" - reportsDir = file("$buildDir/reports/jacoco") + reportsDirectory = layout.buildDirectory.dir("reports/jacoco") } -jacocoTestReport { - reports { - xml.enabled true - csv.enabled false - html.enabled true - html.destination file("${buildDir}/reports/jacoco") - } +tasks.jacocoTestReport { + reports { + xml.required.set(true) + csv.required.set(false) + html.required.set(true) + html.outputLocation.set(layout.buildDirectory.dir("reports/jacoco/html")) + } // what to exclude from coverage report (files that should not be analyzed!) // UI, "noise", generated classes, platform classes, etc. @@ -27,10 +27,12 @@ jacocoTestReport { '**/**IT**.**' // exclude integration tests files ] - getClassDirectories().setFrom(fileTree( - dir: "$buildDir/classes/", - excludes: excludes - )) + classDirectories.setFrom( + files([ + fileTree(dir: "$buildDir/classes/java/main", excludes: excludes), + fileTree(dir: "$buildDir/classes/kotlin/main", excludes: excludes) + ]) + ) // sourceSets sourceSets.main executionData check // include integration tests in jacoco reports diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar index 7454180f..1b33c55b 100644 Binary files a/gradle/wrapper/gradle-wrapper.jar and b/gradle/wrapper/gradle-wrapper.jar differ diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index e750102e..d4081da4 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,5 +1,7 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-7.3-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip +networkTimeout=10000 +validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew index 1b6c7873..23d15a93 100755 --- a/gradlew +++ b/gradlew @@ -15,6 +15,8 @@ # See the License for the specific language governing permissions and # limitations under the License. # +# SPDX-License-Identifier: Apache-2.0 +# ############################################################################## # @@ -55,7 +57,7 @@ # Darwin, MinGW, and NonStop. # # (3) This script is generated from the Groovy template -# https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt +# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt # within the Gradle project. # # You can find Gradle at https://github.com/gradle/gradle/. @@ -80,13 +82,11 @@ do esac done -APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit - -APP_NAME="Gradle" +# This is normally unused +# shellcheck disable=SC2034 APP_BASE_NAME=${0##*/} - -# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. -DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' +# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036) +APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit # Use the maximum available, or set MAX_FD != -1 to use that value. MAX_FD=maximum @@ -114,7 +114,7 @@ case "$( uname )" in #( NONSTOP* ) nonstop=true ;; esac -CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar +CLASSPATH="\\\"\\\"" # Determine the Java command to use to start the JVM. @@ -133,22 +133,29 @@ location of your Java installation." fi else JAVACMD=java - which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + if ! command -v java >/dev/null 2>&1 + then + die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. Please set the JAVA_HOME variable in your environment to match the location of your Java installation." + fi fi # Increase the maximum file descriptors if we can. if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then case $MAX_FD in #( max*) + # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 MAX_FD=$( ulimit -H -n ) || warn "Could not query maximum file descriptor limit" esac case $MAX_FD in #( '' | soft) :;; #( *) + # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 ulimit -n "$MAX_FD" || warn "Could not set maximum file descriptor limit to $MAX_FD" esac @@ -193,18 +200,28 @@ if "$cygwin" || "$msys" ; then done fi -# Collect all arguments for the java command; -# * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of -# shell script including quotes and variable substitutions, so put them in -# double quotes to make sure that they get re-expanded; and -# * put everything else in single quotes, so that it's not re-expanded. + +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +# Collect all arguments for the java command: +# * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, +# and any embedded shellness will be escaped. +# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be +# treated as '${Hostname}' itself on the command line. set -- \ "-Dorg.gradle.appname=$APP_BASE_NAME" \ -classpath "$CLASSPATH" \ - org.gradle.wrapper.GradleWrapperMain \ + -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \ "$@" +# Stop when "xargs" is not available. +if ! command -v xargs >/dev/null 2>&1 +then + die "xargs is not available" +fi + # Use "xargs" to parse quoted args. # # With -n1 it outputs one arg per line, with the quotes and backslashes removed. diff --git a/gradlew.bat b/gradlew.bat index 107acd32..db3a6ac2 100644 --- a/gradlew.bat +++ b/gradlew.bat @@ -13,8 +13,10 @@ @rem See the License for the specific language governing permissions and @rem limitations under the License. @rem +@rem SPDX-License-Identifier: Apache-2.0 +@rem -@if "%DEBUG%" == "" @echo off +@if "%DEBUG%"=="" @echo off @rem ########################################################################## @rem @rem Gradle startup script for Windows @@ -25,7 +27,8 @@ if "%OS%"=="Windows_NT" setlocal set DIRNAME=%~dp0 -if "%DIRNAME%" == "" set DIRNAME=. +if "%DIRNAME%"=="" set DIRNAME=. +@rem This is normally unused set APP_BASE_NAME=%~n0 set APP_HOME=%DIRNAME% @@ -40,13 +43,13 @@ if defined JAVA_HOME goto findJavaFromJavaHome set JAVA_EXE=java.exe %JAVA_EXE% -version >NUL 2>&1 -if "%ERRORLEVEL%" == "0" goto execute +if %ERRORLEVEL% equ 0 goto execute -echo. -echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail @@ -56,32 +59,34 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe if exist "%JAVA_EXE%" goto execute -echo. -echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail :execute @rem Setup the command line -set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar +set CLASSPATH= @rem Execute Gradle -"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* :end @rem End local scope for the variables with windows NT shell -if "%ERRORLEVEL%"=="0" goto mainEnd +if %ERRORLEVEL% equ 0 goto mainEnd :fail rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of rem the _cmd.exe /c_ return code! -if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 -exit /b 1 +set EXIT_CODE=%ERRORLEVEL% +if %EXIT_CODE% equ 0 set EXIT_CODE=1 +if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE% +exit /b %EXIT_CODE% :mainEnd if "%OS%"=="Windows_NT" endlocal