1.12. Python Scripts autodoc

The documentation contained here is auto-generated using Sphinx autodoc (see sphinx.ext.autodoc) from docstrings contained in Python scripts. The scripts documented here are only used in creation of this documentation not for GDA developlment or use.

1.12.1. Common Scripts

These are located in gda-documentation/common/scripts and are used when generating both GDA Developer and User Guides.

1.12.2. GDA Developer Guide Scripts

These are located in gda-documentation/GDA_Developer_Guide/scripts and are used when generating the GDA Developer Guide (this document).

1.12.2.1. extractPyDocs

Parse Python source code to get or print docstrings and create source/python_docs.md.

extractPyDocs.get_docstrings(source, filename)

Parse Python source code and yield a tuple of ast node instance, name, line number and docstring for each function/method, class and module_name.

The line number refers to the first line of the docstring. If there is no docstring, it gives the first line of the class, function or method block, and docstring is None.

extractPyDocs.main()

Parse GDA Python source code to get or print docstrings and create source/python_docs.md.

The root directory of GDA source is obtained from environment variable $WORKSPACE, if this does not exist the default value of ../../ is used, i.e. 2 directories above this script’s location. If $WORKSPACE does exist the root to the GDA source is set to $WORKSPACE/materialize_workspace_git (as used by Jenkins GDA.master-documentation.manuals build job).

Currently the following GDA sources are used:
  • gda-core.git/uk.ac.gda.core/scripts

  • gda-mx.git/configurations/mx-config/scripts

extractPyDocs.print_docstrings(filename, workspace_root, module_name='<string>')

Parse Python source code from file or string and print docstrings.

For each class, method or function and module_name, prints a heading with the type, name and line number followed by the docstring with normalized indentation.

The module_name name is determined from the filename, or, if the source is passed as a string, from the optional module_name argument.

The line number refers to the first line of the docstring, if present, or the first line of the class, function or method block, if there is none. Output is ordered by type first, then name.

1.12.2.2. findDeviceClassesInUse

findDeviceClassesInUse.count_classes(xmlFileList)

Search through all files listed in xmlFileList retrieving names of referenced classes, incrementing total references per class and list of beamlines using the class

Returns 2 OrderedDicts:

classTotalDic - keyed by classname, value is total number of references to class. classBeamlineDic - keyed by classname, value is list of beamlines that reference the class. classNameMaxLen - the maximum length of all class names found

findDeviceClassesInUse.find_config_xml_class_files(configurationDirPath)

Find all .xml files under XX/configurations that contain the string ‘class=’.

Returns: list containing filenames of all xml files found, with path relative to current directory.

1.12.2.3. VisParMaker

VisParMaker.getImportedModules(path)

Parses each file to find imported modules

VisParMaker.main()

This Python script is used to parse GDA Python scripts as classes and determine what other scripts they depend on. The output is a single Python file containing a list of classes which can then be used as input for Visual Paradigm to create Python Relation Diagrams.

1.12.2.4. vp_create_models_and_diagrams

Script used to automatically generate class and sequence diagrams from GDA Java source using Visual Paradigm.

See help text in main() for details.

class vp_create_models_and_diagrams.VpWorker(gda_doc_root, gda_src_root, vp_model_dir, vp_scripts_dir, defn_dic)
create_class_diagrams()

Uses Visual Paradigm script ‘Plugin.sh’ to call GenerateCD VP plug-in to generate the requested class diagrams.

For Plugin.sh see https://circle.visual-paradigm.com/docs/open-api/running-plug-in/running-visual-paradigm-plug-in-silently/

create_models()

Uses Visual Paradigm script ‘InstantReverse.sh’ to create VP model from requested GDA source and store in .vpp project file.

For InstantReverse.sh see https://circle.visual-paradigm.com/docs/export-and-import/command-line-interface/using-instant-reverse-with-command/

create_sequence_diagrams()

Uses Visual Paradigm script ‘InstantReverseSD.sh’ to generate the requested class diagrams.

No Visual Paradigm documentation for ‘InstantReverseSD.sh’ exists but it operates similarly to ‘InstantReverse.sh’ (used by VpWorker.create_models), see https://circle.visual-paradigm.com/docs/export-and-import/command-line-interface/using-instant-reverse-with-command/

export_diagrams()

Uses Visual Paradigm script ‘ExportDiagramImage.sh’ to export requested diagrams from VP model.

For ExportDiagramImage.sh see https://circle.visual-paradigm.com/docs/export-and-import/command-line-interface/exporting-image-with-command/

vp_create_models_and_diagrams.main(defn_meta: ('Meta file', 'option', 'meta', <class 'str'>, None, None) = './scripts/defn_meta.yaml', defn_model: ('Model file', 'option', 'model', <class 'str'>, None, None) = './scripts/defn_models.yaml', diagram: ("Diagrams to create - 'all', 'class' or 'sequence'", 'option', 'd', <class 'str'>, ['all', 'class', 'sequence', ]None) = 'all')

This script uses Visual Paradigm (VP) to:

  • create UML models from Java source code and save them in VP .vpp project files

  • in created .vpp creates class and/or sequence diagrams

  • exports diagrams to .png files for inclusion in GDA documentation

Details of Java source to be used, which diagrams to be created and where they are to be saved are obtained from definition YAML file passed in optional parameter defn_model, default used is defn_models.yaml located in same directory as this script.

This script also requires information about VP install location, top-level or workspace_root directory of GDA source, etc., this information is obtained from YAML file passed in optional parameter defn_meta, default used is defn_meta.yaml located in same directory as this script.

For details of expected structure of definition YAML files see comments in default files in same directory as this script.

During creation of the GDA documentation this script is called by make from this script’s location parent directory using:

make create_dia

If wishing to use non-default definition YAML files use the make target variables:

  • DEFN_MODELS - path to defn_models.yaml file to be used

  • DEFN_META - path to defn_meta.yaml file to be used

E.g if wishing to use different locations than specified in default defn_meta.yaml but create the same diagrams as detailed in defn_models.yaml then only variable DEFN_META needs to be supplied:

make DEFN_META=<path_to>/defn_meta.yaml create_dia

Prior to calling this script the VP class diagram creation plug-in (GenerateCD) must have been built and installed into VP, this is done using:

make vp_plugins

See How to build and install plug-in in GDA Developer’s Guide for details.

Option
-meta, --defn_meta

Location of YAML file detailing information required to run script, e.g. location of Visual Paradigm installation, GDA source workspace_root directory, etc. Default: ./scripts/defn_meta.yaml

Option
-model, --defn_model

Location of YAML file detailing what models and diagrams the script is to create. Default: ./scripts/defn_model.yaml

Option
-d, --diagram

Type of diagrams to create, one of all, class or sequence. Default: all

Option
-h, --help

Show this help message and exit

Returns

OK on success otherwise error code. Exit codes used come from https://docs.python.org/3/library/os.html#os._exit

Example

python vp_create_models_and_diagrams.py

vp_create_models_and_diagrams.read_defn_file(defn_filename)

Read and return contents of definition YAML file in a Python dictionary.

Parameters

defn_filename – Name of YAML file to read.

Returns

success

Logical flag set True on success, i.e. YAML file defn_filename read and dictionary defn_dic successfully created from contents.

defn_dic

Dictionary containing contents of defn_filename YAML file.

vp_create_models_and_diagrams.read_defn_meta(defn_filename)

Read and return contents of definition meta YAML file.

Parameters

defn_filename – Name of definition meta YAML file to read.

Returns

success

Logical flag set True on success, i.e. YAML file defn_filename read and contents retrieved.

gda_doc_root

Path to GDA documentation workspace_root directory.

gda_src_root

Path top-level directory containing GDA source code.

vp_model_dir

Path to directory where created Visual Paradigm model .vpp project files are to be stored.

vp_scripts_dir

Path to Visual Paradigm scripts installation directory.

vp_create_models_and_diagrams.read_defn_models(defn_filename)

Read and return contents of definition model YAML file in a Python dictionary.

Parameters

defn_filename – Name of definition model YAML file to read.

Returns

success

Logical flag set True on success, i.e. YAML file defn_filename read and dictionary defn_dic successfully created from contents.

defn_dic

Dictionary containing contents of defn_filename YAML file.