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