omnicon-ddsdocgen 2.2.1

DDS Document Generator

OmniCon DDS Document Generator - API

Project description

OmniCon Document Generator (DocGen) generates an ICD/documentation from standard DDS type files. The DocGen is utilized via a simple Python API or via a dedicated GUI (see Omnicon DDS DocGen GUI)

Installation

• pip install Omnicon_DDSDocGen
  • Requires: Visual Studio redistributable (https://aka.ms/vs/17/release/vc_redist.x64.exe)
• An Omnnicon license is required to utilize the API. Please Contact [e-mail].

API Usage Example

The following example generates an PDF & Docx ICD from a provided DDS "ShapeType.xml" and a topics mapping, "TopicNamesToTypesDefMap.xml".

from Omnicon_DDSDocGen import DDSDocGen

try:
    doc_gen = DDSDocGen()
except Exception as err:
    print(err)
    exit()

doc_gen.generate_document(
    dds_types_files=["ShapeType.xml"],
    dds_topics_types_mapping="TopicNamesToTypesDefMap.xml",
    version="v1.0",
    title="Demo ICD",
    order_alphabetically=True,
    output_file_name="DemoICD",
    output_folder="",
    output_formats=['pdf', 'docx'])

ShapeType.xml (based on http://www.omg.org/spec/DDS-XML)

<?xml version="1.0" encoding="UTF-8"?>
<types xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <enum name="ShapeFillKind">
    <enumerator name="SOLID_FILL"/>
    <enumerator name="TRANSPARENT_FILL"/>
    <enumerator name="HORIZONTAL_HATCH_FILL"/>
    <enumerator name="VERTICAL_HATCH_FILL"/>
  </enum>
  <struct name= "ShapeType">
    <member name="color" stringMaxLength="128" type="string" key="true"/>
    <member name="x" type="int32"/>
    <member name="y" type="int32"/>
    <member name="shapesize" type="int32"/>
  </struct>
  <struct name= "ShapeTypeExtended" baseType="ShapeType">
    <member name="fillKind" type="nonBasic"  nonBasicTypeName= "ShapeFillKind"/>
    <member name="angle" type="float32"/>
  </struct>
</types>

TopicNamesToTypesDefMap.xml (based on http://www.omg.org/spec/DDS-XML)

<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <domain_library name="Domain_Lib">
    <domain name="Domain">
      <!--Types Definition-->
      <register_type name="ShapeTypeExtended" type_ref="ShapeTypeExtended" />

      <!--Topics Definition-->
      <topic name="Square" register_type_ref="ShapeTypeExtended"/>
    </domain>
  </domain_library>
</dds>

CONSTRUCTOR ARGUMENTS

Argument	Type	Description	Optional	Default value
Logging verbisity	string	Specifies the log verbosity level of choice (DEBUG, INFO, WARNING, ERROR or CRITICAL)	*	"INFO"
progress_callback_function	function	A 'pointer' to the function that updates the progress bar. [(see below)](#Progress Callback Function)	*	(A default function will print to console)

Progress Callback Function

The progress bar callback function provides the user continues updated on the document generation progress. The DocGen will invoke the provided function with the following information:

1. total_steps - total number of steps for the current generation process.
2. current_step - current step the generation process is currently at.
3. info - additional optional textual information regarding the current step (e.g. "saving docx")

ProgressBarCallbackExample(total_steps: int, current_step: int, info: str)    

API Arguments

Argument	Type	Description	Optional	Default value
dds_types_files	list[str]	A list of file or folders names, in an order specified by the user according to files dependencies.
dds_xml_topic_definition	string	An XML file that contains a DDS topic to type mapping. Sending an empty string ("") will switch ICD from topic-based to type-based document	*	(creates type based document)
output_file_name	string	The user's file name of choice	*	"ICD"
title	string	The title/heading of the document. This string will be added to the first page of the document.	*	"ICD"
version	string	The document's version number - This string will be added to the top page of the ICD.	*	"1.0"
order_alphabetically	bool	Select the order of generated document topics/types: alphabetically or according to the loaded files order	*	True (alphabetically)
output_folder	string	The user's output folder of choice	*	current working directory
output_formats	list[str]	A list of desired output formats as strings (list must contain at least one option)

API Return values

The API returns a tuple: (bool, list[str]).

• The boolean indicates whether a document was created (True) or not (False).
• The list of strings holds information regarding the creation of the file(s), such as errors detected in a certain topic/type.

The message format is as follows:

[severity level] [time] - [file format] - [message]

• Severity level: could be one of the following: 'Critical', 'Error', 'Warning', 'Info' or 'Debug'.
• Time: a time stamp, in the following format: yyyy-mm-dd hh:mm:ss.
• File format: Either a PDF or DOCX.
• Message: The information regarding the creation of the specified file

Example:

[ERROR] 2023-03-02 09:17:51.428162 - PDF - Failed to parse topic myTopic . Error : Could not find 'MyType' in provided files!
[INFO] 2023-03-02 09:17:57.693217 - PDF - File saved successfully into 'D:\my\folder\TestingICD.pdf'
[ERROR] 2023-03-02 09:17:57.862493 - DOCX - Failed to parse topic myTopic . Error : Could not find 'MyType' in provided files!
[INFO] 2023-03-02 09:18:01.674094 - DOCX - File saved successfully into 'D:\my\folder\TestingICD.docx'