diff --git a/.gitignore b/.gitignore index 75543ad..ae3ef88 100644 --- a/.gitignore +++ b/.gitignore @@ -283,3 +283,4 @@ local.properties # .nfs files are created when an open file is removed but is still being accessed .nfs* +docs/readthedocs/_build/ \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..90e935b --- /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-20.04 + tools: + python: "3.9" + +# Configure python +python: + install: + - requirements: docs/readthedocs/requirements.txt + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/readthedocs/conf.py \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c04a584 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased Snapshot] + +### Added +- Added ReadTheDocs support [#94](https://github.com/ie3-institute/DWDWeatherTools/issues/94) +- Added a changelog + +### Changed + +### Fixes diff --git a/README.md b/README.md index a15ef56..61ddfc5 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ the whole area. |vertical levels | 60 level | |upper boundary | 22.5km | -![](doc/img/icon-eu-nest.png) +![](docs/readthedocs/_static/img/icon-eu-nest.png) In contrast, the converter area can be set in the code to the area of interest. @@ -88,7 +88,7 @@ In the future it would make sense to provide the coordinates via a config file instead of hard-coding them into the binary. If you want to provide this future feel free to hand in an issue or a pull request. -![](doc/img/converter_covered_area.jpg) +![](docs/readthedocs/_static/img/converter_covered_area.jpg) ### Requirements diff --git a/build.gradle b/build.gradle index d773362..485a701 100644 --- a/build.gradle +++ b/build.gradle @@ -11,6 +11,7 @@ plugins { id 'com.github.onslip.gradle-one-jar' version '1.0.6' // pack a self contained jar id 'jacoco' // java code coverage plugin id "org.sonarqube" version "3.3" // sonarqube + id "kr.motd.sphinx" version "2.10.0" } ext { diff --git a/docs/readthedocs/Makefile b/docs/readthedocs/Makefile new file mode 100644 index 0000000..bfd7a7e --- /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 ?= python3 -msphinx +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 0000000..914a128 --- /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; +} \ No newline at end of file diff --git a/doc/img/converter_covered_area.jpg b/docs/readthedocs/_static/img/converter_covered_area.jpg similarity index 100% rename from doc/img/converter_covered_area.jpg rename to docs/readthedocs/_static/img/converter_covered_area.jpg diff --git a/doc/img/icon-eu-nest.png b/docs/readthedocs/_static/img/icon-eu-nest.png similarity index 100% rename from doc/img/icon-eu-nest.png rename to docs/readthedocs/_static/img/icon-eu-nest.png diff --git a/docs/readthedocs/conf.py b/docs/readthedocs/conf.py new file mode 100644 index 0000000..a276c49 --- /dev/null +++ b/docs/readthedocs/conf.py @@ -0,0 +1,72 @@ +# 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 = 'DWDWeatherTools' +copyright = u'2022. TU Dortmund University, Institute of Energy Systems, Energy Efficiency and Energy Economics, Research group Distribution grid planning and operation ' +author = 'Johannes Hiry, Debopama Sen Sarma, Chris Kittl, Sebastian Peter, Thomas Oberließen' + +# The full version, including alpha/beta/rc tags +version = '0.1.' +release = '0.1.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 = [ + 'sphinx.ext.autosectionlabel', + 'myst_parser' +] + +# 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 = "DWDWeatherTools" +htmlhelp_basename = 'DWDWeatherTools-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 0000000..242feec --- /dev/null +++ b/docs/readthedocs/index.rst @@ -0,0 +1,31 @@ +Documentation of the DWDTools +========================================= + +Hello weather! + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + user/users + + + +Contact the (Main) Maintainers +------------------------------ +If you feel, something is missing, wrong or misleading, please contact one of our main contributors: + + * `@sensarmad `_ + * `@johanneshiry `_ + * `@ckittl `_ + * `@t-ober `_ + * `@sebastian-peter `_ + +Hat tip to all other contributors! + +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 0000000..922152e --- /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.http://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 0000000..e014332 --- /dev/null +++ b/docs/readthedocs/requirements.txt @@ -0,0 +1,3 @@ +myst-parser==0.16.1 +Sphinx==4.2.0 +sphinx-rtd-theme==1.0.0 \ No newline at end of file diff --git a/docs/readthedocs/user/users.md b/docs/readthedocs/user/users.md new file mode 100644 index 0000000..a6be67b --- /dev/null +++ b/docs/readthedocs/user/users.md @@ -0,0 +1,3 @@ +# Users Guide + +You got this! diff --git a/gradle/scripts/spotbugs.gradle b/gradle/scripts/spotbugs.gradle index 2483fd7..c9b9a7c 100644 --- a/gradle/scripts/spotbugs.gradle +++ b/gradle/scripts/spotbugs.gradle @@ -4,6 +4,7 @@ spotbugs{ ignoreFailures = true // dont let the build fail on rule violations effort = 'max' reportLevel = 'high' + excludeFilter = file('spotbugs-exclude.xml') } spotbugsMain{ diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml new file mode 100644 index 0000000..b07473a --- /dev/null +++ b/spotbugs-exclude.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file