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.1.1. create_broken_links_md¶
Script used to produce documents_broken_links.md
.
Uses the .json
files output by make targets linkcheck
and linkcheck_local
to produce a new version of
documents_broken_links.md
from a
Jinja template. The new page
contains tables detailing all broken external and internal links.
Following use of this script the make target html
is to be used
to build the new version of the page into the document.
Note: the Jinja templating language was chosen for use by this script as this is the language used by Sphinx, therefore all packages required for its use are already available as they are required to build the GDA documentation.
-
create_broken_links_md.
main
(linkcheck_dir: ('Path to build directory containing linkcheck ouptput .json files', 'positional', None, <class 'str'>, None, None), md_template: ('Name of markdown template file to be used to create documents_broken_links.md', 'positional', None, <class 'str'>, None, None), log: ('Set logging level (default=off)', 'option', 'l', <class 'str'>, ['off', 'info', 'debug', ]None), log_file: ('File for log output; none (default) log to stdout', 'option', 'f', <class 'str'>, None, None))¶ Uses linkcheck
.json
output files to create newdocuments_broken_links.md
source file detailing document’s broken links.- Parameters
linkcheck_dir – Path to build directory containing linkcheck output .json files, e.g.
build/linkcheck
md_template – Name of markdown
.md
template file to be used to create documents_broken_links.md, e.g.source/appendix/documents_broken_links.template
- Option
- -l, --log
One of
off
,info
ordebug
, default isoff
- Option
- -f, --log_file
Only in conjunction with
-l
, name of file for log output, default isNone
, log to stdout.
- Returns
OK on success otherwise error code. Exit codes used come from https://docs.python.org/3/library/os.html#os._exit
- Example
python ../common/scripts/create_broken_links_md.py build/linkcheck source/appendix/documents_broken_links.template
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 usedDEFN_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 indefn_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
orsequence
. 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 filedefn_filename
read and dictionarydefn_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 filedefn_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 filedefn_filename
read and dictionarydefn_dic
successfully created from contents.- defn_dic
Dictionary containing contents of defn_filename YAML file.