Tools and More

Nested functions to sphinx/rst

Note

The room callbacks are a special case with their own script rst_nested_function_generator.get_nested_function_docstrings_room().

The problem is that the callback functions are nested function in a top level function in each callback file. This is done to distribute them over several files and make the structure of the project cleaner. The problem in documenting them is that SPHINX does not recognize nested function docstrings with the “automodule” command. This is where these scripts jump in. They create a new python file in the /docs folder, which contain all the functions and docstrings without code at top level.

rst_nested_function_generator.get_nested_function_docstrings(filename, output_file_name, function_name)

This function takes a file with a top level function in it, which contains nested functions. It creates a new python file with all nested function and their docstrings in it. This file then can be read by Sphinx.

Parameters:

• filename (str) – Name of file including the nested functions

• output_file_name (str) – Name of output file

• function_name (str) – Name of top level function containing nested functions

Returns:

Nothing

rst_nested_function_generator.get_nested_function_docstrings_room(filename, output_file_name, function_names)

Only for room_callbacks file! This function takes a file with multiple top level functions in it, which contains nested functions. They are specified in the “function_names” input. It creates a new python file with all nested function and their docstrings in it. It also adds the docstring of the room_callback function. This file then can be read by Sphinx.

Parameters:

• filename (str) – Name of file including the nested functions

• output_file_name (str) – Name of output file

• function_names (list[str]) – Names of top level function containing nested functions

Returns:

Nothing