tlo.docs module

The functions used by tlo_methods_rst.py.

get_package_name(dirpath)

Given a file path to a TLO package, return the name in dot form.

Parameters:

dirpath – the path to the package, e.g. (1) “./src/tlo/logging/sublog” or (2) “./src/tlo”

Returns:

string of package name in dot form, e.g. (1) “tlo.logging.sublog” or (2) “tlo”

generate_module_dict(topdir)

Given a root directory topdir, iterates recursively over top dir and the files and subdirectories within it. Returns a dictionary with each key = path to a directory (i.e. to topdir or one of its nested subdirectories), and value = list of Python .py files in that directory.

Parameters:

topdir – root directory to traverse downwards from, iteratively.

Returns:

dict with key = a directory, value = list of Python files in dir key.

get_classes_in_module(fqn, module_obj)

Generate a list of lists of the classes defined in the required module (file), in the order in which they appear in the module file. Note that this excludes any other classes in the module, such as those brought in by inheritance, or imported.

Each entry in the list returned is itself a list of: [class name, class object, line number]

Parameters:

  • fqn – Fully-qualified name of the module, e.g. “tlo.methods.mockitis”

  • module_obj – an object representing this module

  • return – list of entries, each of the form: [class name, class object, line number]

get_fully_qualified_name(filename, context)

Given a file name and a context return the fully-qualified name of the module

e.g. tlo.methods.mockitis This gets used in doc page title.

Parameters:

  • filename – name of file, e.g. “mockitis.py”

  • context – “location” of module, e.g. “tlo.methods”

Returns:

a string, e.g. “tlo.methods.mockitis”

write_rst_file(rst_dir, fqn, mobj)

We want to write one .rst file per module in ./src/tlo/methods

Parameters:

  • rst_dir – directory in which to write the new .rst file

  • fqn – fully-qualified module name, e.g. “tlo.methods.mockitis”

  • mobj – the module object

get_class_output_string(classinfo)

Generate output string for a single class to be written to an rst file.

Parameters:

classinfo – a list with [class name, class object, line number]

Returns:

the string to output

which_functions_to_print(clazz)

Which functions do we want to print?

Parameters:

clazz – class object under consideration

Returns:

returns a list of function objects we want to print

Written by Asif

extract_bases(class_name, class_obj, spacer='')

Document which classes this class inherits from, except for the object class or this class itself.

Parameters:

  • class_name – name of the class (e.g. Mockitis) for which we want the bases

  • class_obj – object with information about this class

  • spacer – string to use as whitespace padding.

Returns:

Tuple with (1) string of base(s) for this class (if any), with links to their docs. (2) the list of base class objects

get_base_string(class_name, class_obj, base_obj)

For this object, representing a base class, extract its name and add a hyperlink to it. Unless it is the root ‘object’ class, or the name of the class itself.

Parameters:

  • class_name – the name of the class (e.g. “Mockitis”) for which obj is a base,

  • class_obj – object representing the class

  • base_obj – the object representation of the base class, e.g. <class ‘tlo.core.Module’> or <class ‘object’> or <class ‘tlo.methods.mockitis.Mockitis’>

Returns:

string as hyperlink

Given a name like Mockitis and a base_string like tlo.core.Module, create a link to the latter’s doc page.

Parameters:

  • base_fqn – fully-qualified name of the base class, e.g. tlo.core.Module

  • base_obj – the object representing the base class

Returns:

a string with the link to the base class’s place in the generated documentation.

create_table(mydict)

Dynamically create a table of arbitrary length from a PROPERTIES or PARAMETERS dictionary.

Parameters:

mydict – the dictionary object.

Returns:

A list of strings, used for output.

NB Do not change the positioning of items in the f-strings below, or things will break!

The table is returned as a list of strings. If there is no data, an empty list is returned.