API Style Guide

This topic describes the structure of the PythonApi and JythonApi topics and what the individual topics are supposed to look like.

Access

The start page is divided into Customizing and Server.

• Modules that are documented go in the respective table
• Packages receive an extra heading with their own table

Format

* The general rule is:

• Python objects must either have a link to the documentation of the class/function or be formatted in verbatim
  • This also applies to constants like True or False

Module Topics

A module topic is always structured as follows:

• classes
  • static variables
  • methods
  • class methods
  • static methods
  • properties
• functions

Classes

In this area, the classes of the module are listed.

• At the top position there can be a class diagram, if considered helpful
• For each class there can be a short text describing what the use of the class is

Static Variables

In table form, static variables are described as follows:

Variable	Description
NameOfTheClass.NAME_OF_THE_PARAMETER	A short text which described the variable

Methods / Class Methods / Static Methods

In table form, methods are described as follows:

Function	Parameters	Return Value	Description
NameOfTheClass.name_of_the_function(self, a_mandatory_parameter, a_keyword_argument='Default Value')	mandatory_parameter: Here we describe the parameter a_keyword_argument: Here we describe the parameter	What this method returns	A description of the method.

The following must be observed:

• Keyword arguments are in Italics and are described with their default value
• In the parameter descriptions there is a one-line gap between arguments and keyword
• If an argument can be ascribed to a data item in PLANTA, e.g. the project ID, then the argument can simply be documented with a reference to the respective DI. In this case the Project ID
  • Primary keys are to be favored over foreign keys As an example one could think of a Task class which describes a 463 and is initialized with project and task ID. In this case, a reference to DI 001001 via 001097 is to be favored for the project ID.
• If the expected value can be found in a enum/constant, the respective position should be linked.
• The argument description is only to describe the data/value type that the function expects. Complex arguments are to be explained in the description

Properties

In table form, properties are described as follows:

Property	Getter	Setter	Description
NameOfTheClass.name_of_the_property			A short text which described the property

Here, the same rule applies:

• If a property is directly linked to a data item in PLANTA, simply link the respective data item