omnicon-ddsdocgen 2.1.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.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>

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)
progress_callback_function	function	A 'pointer' to the function that updates the progress bar. [(see below)](#Progress Callback Function)	*	None

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 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'