microspeclib.internal.docstrings module

Automated and static docstrings for json-generated classes, functions, and globals

Most of the API objects in MicroSpecLib are dynamically generated from cfg/microspec.json. For example CommandSetBridgeLED, MicroSpecSimpleInterface.setBridgeLED, and LEDGreen are not defined in code, they are created by meta-class factories, so that if the configuration changes to permit new protocol commands and replies, the functions and classes will automatically update as well. However, this causes a problem for documentation.

Great pains were taken to auto-generate the proper function and class signatures such as CommandSetBridgeLED(led_num=None, led_setting=None) rather than just CommandSetBridgeLED(*args, **kwargs), so that pydoc and sphinx could introspect and document them properly. However, the ONE thing that cannot be auto-generated is the per-function and per-class human-read documentation. It could go into yet another json file and be auto-generated, but that would be no more compact than making a file elsewhere for it. It could be written directly in sphinx doc/source/*.rst files, but then pydoc wouldn’t find them. So the only choice left is to make a separate internals docstrings library with the data in one place there, and that is what this module is. Luckily, it at least saves some repetition, since both CommandSetBridgeLED and MicroSpecSimpleInterface.setBridgeLED need the same documentation, for example.

Thus, this module contains dictionaries for the different data and class types, and the datatype module imports and implements them when it instantiates the metaclasses and generates the globals. Since the json protocol and the documentation are separate, we must assume that one might get out of sync with the other, thus it is assumed that this documentation may be missing something. As such, implementers of these dictionaries should use DOC.get(value, None) and handle lack of documentation in a responsible way.

The CHROMASPEC_DYNAMIC_DOC[“command”][“CommandGetBridgeLED”] contains that docstring, for example.

And the _common global is used to hold common replacement patterns, to eliminate having to type the same things over and over below - they are replaced at the end of the module.