Can Plugins self-document what they define?

[john-science]

An ArmiPlugin can define several things for a simulation. I see two options:

1. the class stored a short list-of-strings with the names of each one of the things they define
2. a helper method to call to produce that list

This would make documentation easier. It would also make it easier to audit if a Parameter or Setting is still being used.

I suspect this will be easy to do.

Important Examples

armi/armi/plugins.py

Line 188 in 3049a0c

def defineParameters() -> Dict:

armi/armi/plugins.py

Line 422 in 3049a0c

def defineSettings() -> List:

But Also

armi/armi/plugins.py

Line 287 in 3049a0c

def defineFlags() -> Dict[str, Union[int, flags.auto]]:

armi/armi/plugins.py

Line 316 in 3049a0c

def defineBlockTypes() -> List:

armi/armi/plugins.py

Line 335 in 3049a0c

def defineAssemblyTypes() -> List:

armi/armi/plugins.py

Line 371 in 3049a0c

def defineBlueprintsSections() -> List:

armi/armi/plugins.py

Line 407 in 3049a0c

def defineEntryPoints() -> List:

armi/armi/plugins.py

Line 459 in 3049a0c

def defineSettingsValidators(inspector) -> List:

armi/armi/plugins.py

Line 491 in 3049a0c

def defineCaseDependencies(case, suite):

[john-science]

@jakehader Just FYI. This was my idea. I think I can knock this out pretty fast.

[drewj-tp]

I'm wondering about the why here. Is it to make generating API docs easier? The plugins already have the hooks that describe what expose / configure / define / etc.

A sphinx directive could help w/ the docs by calling e.g., Plugin.defineParameters and parse the returned dictionary with relative ease. Similarly for the other things.

Or something like Plugin.gatherAllDefines that just calls the hooks defined on the class and collects those definitions?

[john-science]

I'm wondering about the why here.

As I said above "It would also make it easier to audit if a Parameter or Setting is still being used." I have seen literally hundreds of parameters go unused for years because some team lost track of the fact they created it and they stopped using it.

The "problem" in ARMI is we made it really easy to create new settings, parameters, flags, etc. But it is even easier to stop using them and leave them around, uselessly cluttering a simulation.

A sphinx directive could help w/ the docs by calling e.g., Plugin.defineParameters

Sure! Something like that fits nicely into option (2) above.