Customizing
Customizing
Breadcrumbs

API Style Guide

This topic describes the structure of the PythonApi and JythonApi topics and what the individual topics should 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 Monospace

    • 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 module classes 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

Static variables are described in table form as follows:

Variable

Description

NameOfTheClass.NAME_OF_THE_PARAMETER

A short text which describes the variable

Methods / Class Methods / Static Methods

Methods are described in table form 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.

Note the following:

  • Keyword arguments are in italics and are filled 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 data table and is initialized with project and task ID. In this case, a reference to DI001001 via DI001097 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 which the function expects. Complex arguments are to be explained in the description.

Properties

Properties are described in table form as follows:

property

getter

setter

Description

NameOfTheClass.name_of_the_property

A short text which describes the property

Here too:

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