Documentation of config

[benjimin]

A single config file is the main user-interface for TCRM, so it needs to be properly documented for new users. Part of the current arrangement makes this particularly challenging to maintain.

Currently there is no single place with complete documentation for a user to understand which fields are needed and how those values will affect the simulation. In the code for TCRM, there are about a thousand lines which mention config (988-1485 depending whether two relic GUI config editors are excluded), spanning 62 files. Although there is only a single config file (which needs to be read/parsed only once), ConfigParser occurs 117 times (in 53 files), and within a single entry point (tcrm.py) there are (superfluously) a dozen repetitions of config.read. The entire config is treated as a defacto global state (by pervasive passing of alternately the path or the parsed object), making it nontrivial to infer which parts of TCRM are influenced by which configuration parameters.

This may have overlap with other issues e.g. #65, #66, #67.

A readily maintainable solution could include one exhaustively commented example config file, that is both linked in from the docs and executed by a routine system test; and arranging TCRM so that the config file is parsed and interpreted in a single section and submodules are explicitly passed the subset of parameters which they use.

[wcarthur]

'Output'  'Path'
'Output'  'Format'
'Output', 'ColourMap' 
'Output'  'Working_dir'

'Process'  'DatFile'

'DataProcess'  'InputFile'
'DataProcess'  'Source'

source  'filename'
source  'path'
source  'FieldDelimiter'
source  'Columns'
source  'DateFormat'
source  'SpeedUnits'
source  'PressureUnits'
source  'LengthUnits'

'Input'  'CoastlineGates'
'Input'  'Landmask'
'Input'  'RawMultipliers'
'Input'  'MSLPFile'
'Input' MSLPVariableName'
'Input'  'LocationFile'
'Input', 'Datasets'
'Input'  'Multipliers'
'Input'  'Tiles'
'Input'  'Gust_file'

'Impact'  'Exposure'
'Region'  'LocalityID'

'Hazard'  'ExtremeValueDistribution'
'Hazard'  'PlotSpeedUnits'

'StatInterface'  'kdeType'

'Logging' 'LogFile'
'Logging'  'LogLevel'
'Logging'  'ProgressBar'

'TrackGenerator'  'Format'

dataset  'URL'
dataset  'path'
dataset  'filename'

'Timeseries'  'LocationFile'
'Timeseries'  'StationID'
'WindfieldInterface'  'profileType'
'WindfieldInterface'  'windFieldType'
'WindfieldInterface'  'Domain'
'WindfieldInterface' 'Resolution'
'WindfieldInterface' 'Margin'