autogenerate_parameter_docs

Generates .yml format descriptions of the parameters in the C files.

This script goes through the (non-blacklisted) input .c files, and identifies the input variables, their types and any notes (e.g. units, choices).

It then compares this list to the existing documentation files, and lists which existing documentation refers to parameters that are now deprecated, and which parameters that are new and yet to be documented.

By default, the script will simply print the new and deprecated files to the screen.

param -p / –print:

Print the full text of all .yaml files that would be created to the screen.

param -w / –write:

Move any deprecated parameters to $SIROCCO/parameters/old/, then write any new parameters to in $SIROCCO/parameters/

Note, this will not over-write any parameters that have changed types but not names e.g. rdflo(‘thing’) to rdint(‘thing’).

param -h / –help:

Prints this documentation.

After the program has been run $SIROCCO/parameters should contain a yaml file for every possible input, and any input that has changed significantly should be in $PYHON/parameters.old One should normally be sure to add the new yaml files to the repository.

Note

This routine does not autormatial add new yaml files that have been created to the git repository, though it is possible that should be the default.

Therefore if one uses the -w option, it will create new files, and these will remaing in the local repositiory, even if one changes branches. This can be confusing!!!

The program checks which files in the directories it writes to are not committed, but it is up to the user to sort out what s/he wants to do.

The command to list files in a directory that are not tracked is:

git ls-files --other

if one is in the directory in question.

The command to remove files in a directory (from within that directory) is:

git clean -f

The recommendation is to:

• to clean both $SIROCCO/parameters/, and $SIROCCO/parameters/old/ from your local directories before using writing files using this routine, and then

• to add and comit all of the files that are produced before going on to other stages of activities associated with documentation.

Functions

autogenerate_parameter_docs()	Function to autogenerate parameter documentation.
deprecate_documentation(...)	Moves any deprecated documentation to the archive folder.
intersect_documentation(...)	Intersections of documentation
list_existing_documentation(directory)	Look through the output folder, and record every .yaml file in it.
list_input_files(directory)	Look through the source folder, and track each file that isn't in the blacklist.
my_represent_scalar(self, tag, value[, style])	Replacement 'representer' for strings that intelligently switches between single- and multi-line output
parse_param_to_dict(found_parameters, ...)	Given a string that's the text of a c function call for a parameter, decide if this is a parameter and return so.
read_parameters(input_folder, input_files, ...)	For each input file, process and add to found parameters list.
should_use_block(value)	Whether or not this string is multi-line and should use the '|' literal string format
yaml_output(output_dict, new_documentation, ...)	Prints out new documentation to screen or writes it to file.