Commit 5f343f30 authored by Lukas Riedel's avatar Lukas Riedel Committed by Santiago Ospina De Los Ríos

Write parameter version attributes into user docs

Attributes are sorted by decreasing version.
parent cedc75d3
......@@ -8,6 +8,8 @@ We're rolling out version `X.Y.0`! :tada:
`dune.module` to `X.Y.0`.
- [ ] `master`: Update all `version="unreleased"` tags in the default config
file XML sources to `version="X.Y.0"`.
- [ ] `master`: Update all [version directives][sphinx-ver-dir] with version
`unreleased` in the user docs to `X.Y.0`.
### 2 — On GitLab
- [ ] [Create branch][new branch] `X.Y-stable` from `master`
......@@ -47,3 +49,4 @@ Close this issue!
[new label]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/labels/new
[DockerHub description]: https://hub.docker.com/r/dorie/dorie
[badge]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/edit
[sphinx-ver-dir]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
......@@ -13,6 +13,8 @@ The MRs to be considered in this update are listed in #
- [ ] Update version numbers in `VERSION`, `CHANGELOG.md`, `dune.module`
- [ ] Update `version="unreleased"` tags in the default config file XML
sources <!-- only if applicable -->
- [ ] Update Sphinx version directives with version `unreleased` in the user
docs. <!-- only if applicable -->
#### Help on Cherry-Picking
Cherry-picking merge commits requires specifying the "mainline" parent, which
......
......@@ -32,6 +32,7 @@
* Parameter XML files support tags for version changes !171
* Unit test for Parameter XML file parser !171
* CMake option to enable code coverage flags on all targets !172
* Changes to config file parameters listed per version in user docs !175
### Changed
* Data structures for storing and accessing parameter information !55
......
......@@ -26,6 +26,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> richards </suggestion>
<values> richards, richards+transport </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
......@@ -84,6 +85,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> path </values>
<suggestion> None </suggestion>
<comment> This category is only used for 'rectangular' grids </comment>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="volume">
......@@ -93,6 +95,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 0 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryLower">
......@@ -102,6 +105,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 0 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryUpper">
......@@ -111,6 +115,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 1 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryLeft">
......@@ -120,6 +125,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 2 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryRight">
......@@ -129,6 +135,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 3 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryFront">
......@@ -139,6 +146,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<suggestion> 4 </suggestion>
<values> path or int </values>
<comment> Only in 3D </comment>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="boundaryBack">
......@@ -148,6 +156,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> 5 </suggestion>
<values> path or int </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
......@@ -160,6 +169,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> none, waterFlux </values>
<suggestion> none </suggestion>
<comment> none, waterFlux </comment>
<versionadded version="unreleased"> Replaces ``useAdaptivity``.
</versionadded>
</parameter>
<parameter name="maxLevel">
......@@ -201,6 +212,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> elementFraction, errorFraction, threshold </values>
<suggestion> elementFraction </suggestion>
<comment> elementFraction, errorFraction, threshold </comment>
<versionchanged version="unreleased"> Option ``targetTolerance`` removed.
</versionchanged>
</parameter>
<parameter name="refinementFraction">
......@@ -230,6 +243,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<suggestion> info </suggestion>
<values> trace, debug, info, warning, error, critical </values>
</parameter>
<versionadded version="unreleased"> </versionadded>
</category>
<category name="misc">
......
......@@ -29,6 +29,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
The dataset name inside the ``outputFile``.
</definition>
<values> path </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="converter">
......@@ -40,6 +41,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> none, binary, exponential </values>
<suggestion> binary </suggestion>
<comment> none, binary, exponential </comment>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="tempDir">
......@@ -49,6 +51,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> path </values>
<suggestion> /tmp/fft_generator/ </suggestion>
<versionchanged version="unreleased"> Renamed from
``generator.fft.outputPath``. </versionchanged>
</parameter>
</category>
......@@ -57,6 +61,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<definition> Physical dimensions of the field. </definition>
<suggestion> 2 </suggestion>
<values> 2, 3 </values>
<versionchanged version="unreleased"> Renamed from
``generator.dimensions``. </versionchanged>
</parameter>
<parameter name="extensions">
......@@ -66,6 +72,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> int &times; int (&times; int) </values>
<suggestion> 1 1 </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="cells">
......@@ -73,6 +80,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> int &times; int (&times; int) </values>
<suggestion> 100 100 </suggestion>
<versionchanged version="unreleased"> Renamed from ``generator.fft.N``.
</versionchanged>
</parameter>
</category>
......@@ -85,6 +94,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> int </values>
<suggestion> 1 </suggestion>
<versionchanged version="unreleased"> Renamed from
``generator.fft.seed``. </versionchanged>
</parameter>
<parameter name="variance">
......@@ -93,6 +104,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> float </values>
<suggestion> 0.2 </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="corrLength">
......@@ -101,6 +113,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> float &times; float (&times; float) </values>
<suggestion> .1 .05 </suggestion>
<versionchanged version="unreleased"> Renamed from
``generator.fft.correlationLenghts``. </versionchanged>
</parameter>
<parameter name="covariance">
......@@ -109,6 +123,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> exponential, gaussian, spherical, whiteNoise </values>
<suggestion> gaussian </suggestion>
<comment> exponential, gaussian, spherical, whiteNoise </comment>
<versionchanged version="unreleased"> Renamed from
``generator.fft.covariance``. </versionchanged>
</parameter>
</category>
......@@ -120,6 +136,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> int </values>
<suggestion> 0 1 </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
......@@ -133,6 +150,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> bool </values>
<suggestion> true </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
</dorie>
......@@ -20,6 +20,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<definition> Logging level of the Richards solver. </definition>
<suggestion> info </suggestion>
<values> trace, debug, info, warning, error, critical </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="outputPath">
......@@ -48,6 +49,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<definition> Policy to write the data. </definition>
<suggestion> endOfRichardsStep </suggestion>
<values> endOfRichardsStep, none </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="subsamplingLevel">
......@@ -78,6 +80,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<suggestion> infiltration.yml </suggestion>
</definition>
<values> path </values>
<versionchanged version="unreleased"> Expects a YAML file now.
</versionchanged>
</parameter>
</category>
......@@ -89,6 +93,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> data, analytic </values>
<suggestion> analytic </suggestion>
<comment> Choose initial condition type: data, analytic </comment>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="quantity">
......@@ -98,12 +103,14 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> matricHead </values>
<suggestion> matricHead </suggestion>
<comment> Choose quantity represented: matricHead </comment>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="equation">
<definition> Equation for the initial condition </definition>
<values> equation [x,y,z,h] </values>
<suggestion> -h </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="file">
......@@ -112,12 +119,14 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
file extension ``.h5``.
</definition>
<values> path </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="dataset">
<definition> Dataset to use as initial condition (``data`` type only).
</definition>
<values> string </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="interpolation">
......@@ -125,6 +134,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> nearest, linear </values>
<suggestion> linear </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
......@@ -199,6 +209,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<values> path </values>
<suggestion> richards_param.yml </suggestion>
</parameter>
<versionadded version="unreleased"> </versionadded>
</category>
<category name="numerics">
......@@ -210,6 +221,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<suggestion> 1 </suggestion>
<values> 0, 1, 2, 3 </values>
<comment> Select '0' for the finite volume (FV) solver </comment>
<versionchanged version="unreleased"> Renamed from ``grid.FEorder``.
</versionchanged>
</parameter>
<parameter name="upwinding">
......@@ -225,6 +238,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
<suggestion> none </suggestion>
<comment> Choose upwinding type: 'none', 'semiUpwind', 'fullUpwind'
</comment>
<versionchanged version="unreleased"> Renamed from
``dg.experimental.upwinding``. </versionchanged>
</parameter>
<parameter name="DGMethod">
......@@ -240,6 +255,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> SIPG, NIPG, OBB, IIP </values>
<suggestion> SIPG </suggestion>
<versionchanged version="unreleased"> Renamed from
``dg.experimental.method``. </versionchanged>
</parameter>
<parameter name="DGWeights">
......@@ -248,6 +265,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> true, false </values>
<suggestion> true </suggestion>
<versionchanged version="unreleased"> Renamed from
``dg.experimental.weights``. </versionchanged>
</parameter>
<parameter name="penaltyFactor">
......@@ -255,6 +274,8 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> float </values>
<suggestion> 10 </suggestion>
<versionchanged version="unreleased"> Renamed from
``dg.penaltyFactor``. </versionchanged>
</parameter>
</category>
......@@ -267,6 +288,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> true </suggestion>
<values> true, false </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="checkJumps">
......@@ -277,6 +299,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<suggestion> none </suggestion>
<values> none, warn, error </values>
<versionadded version="unreleased"> </versionadded>
</parameter>
<parameter name="checkTol">
......@@ -285,6 +308,7 @@ A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
</definition>
<values> float &gt; 0 </values>
<suggestion> 1E-10 </suggestion>
<versionadded version="unreleased"> </versionadded>
</parameter>
</category>
......
......@@ -63,6 +63,13 @@ Parameter Field Generator
Main Routine
------------
Common and richards parameters are needed in the configuration file.
Depending on the ``simulation.mode``, the respective model categories will be
read. The parameters without model prefix are always evaluated.
.. versionadded:: unreleased
Added ``transport`` model parameters.
.. versionchanged:: unreleased
Split parameters into default and ``richards`` model parameters.
.. include:: @CHEATSHEET_DORIE_RELPATH@
......@@ -4,6 +4,7 @@ import datetime
import os
import re
import textwrap
from distutils.version import LooseVersion
try:
str = unicode
......@@ -23,6 +24,15 @@ def write(parameters,out,path_base,*args,**kwargs):
<description>
.. deprecated: <ver>
[description]
.. versionchanged: <ver>
[description]
.. versionadded: <ver>
[description]
Possible values | <values>
Default value | <suggestion>
Queried at | <file path (if available)>
......@@ -70,6 +80,24 @@ def _format_parameter(parameter, path_base):
out += "\n"
out += "\n"
# Changes by version
def write_version_attr(param, attr_name):
data_dict = getattr(param, attr_name)
versions_sorted = sorted(data_dict.keys(),
key=LooseVersion,
reverse=True)
nonlocal out
for version in versions_sorted:
out += tab + ".. {0}:: {1}\n".format(attr_name, version)
description = data_dict[version]
if description:
out += tab + tab + description + "\n"
out += "\n"
write_version_attr(parameter, "deprecated")
write_version_attr(parameter, "versionchanged")
write_version_attr(parameter, "versionadded")
# Table
out += tab + ".. list-table::\n"
out += tab + tab + ":widths: auto\n\n"
......@@ -95,7 +123,7 @@ def _format_parameter(parameter, path_base):
return out
def _format_heading(text):
text = "Category: ``{}``".format(text)
text = "Category: ``[{}]``".format(text)
sep = "+"*len(text)
return text + "\n" + sep + "\n\n"
......
......@@ -10,6 +10,7 @@ from yaml import unsafe_load
from dorie.parscraper import writers
from dorie.parscraper.parameter import Parameter
from dorie.parscraper.warnings import OutputWarning
def write(data, args):
# CALL OUTPUT SCRIPTS
......@@ -17,19 +18,10 @@ def write(data, args):
file_suffix = out.split(".")[-1]
if hasattr(writers, file_suffix):
writer = getattr(writers, file_suffix)
try:
writer.write(data,
out,
args.source,
css=args.css)
except BaseException as e:
if file_suffix == "ini":
raise
else:
warnings.warn("Output failed for file {0} with error:\n{1}".format(out, repr(e)), OutputWarning)
if args.debug:
exc_type, exc_value, exc_traceback = sys.exc_info()
traceback.print_exception(exc_type, exc_value, exc_traceback)
writer.write(data,
out,
args.source,
css=args.css)
else:
warnings.warn("Unknown output format: .{}. Skipping output".format(file_suffix), OutputWarning)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment