How to Write Trait Documentation

Follow this guide for writing documentation on traits and how to use them. The following sections and headlines mimic how the documentation should be structured.

General rules:

  • For mentioning custom data types, class names etc. in the text, use backticks (`…`) to mark them as such.

  • Use title case for the headlines (all words capitalized, except for minor words (articles, prepositions, conjunctions))

Summary of What the Trait Does

This subsection is the introduction, which provides a general description of what the user might want to achieve in their application, along with some context. It should be made clear that the problem at hand can be addressed using the methods described in this chapter without going into too much detail just yet. Do not mention anything about traits or the trait concept here, since implementation details are not relevant to the user.

Explaining What the First Trait Method Does

Describe what the first available method of the trait can be used for. Without mentioning anything about the trait itself or the trait concept, explain how the method can be called and give a short code example via a literalinclude statement, as shown below:

```{literalinclude} /docs_src/developer/how_to_write_trait_docu.py
  :language: Python
  :start-at: robot.move_ptp(HOME).result()
  :end-at: robot.move_ptp(HOME).result()
  :dedent:
```

which will be rendered as:

robot.move_ptp(HOME).result()

The expected return type and side effects of the method should be described. If it is helpful, an example of what a logged output looks like can be added:

[INFO] The current ... is ...

If it applies, the requirements which have to be fulfilled to use this method have to be explained.

Explaining What the Second Trait Method Does

Add multiple sections explaining the different trait methods, if a trait has multiple methods.

Full Application Example

Each trait should contain an application example, imported via a literalinclude statement, following these rules:

  • The example code must be executable without errors.

  • Refrain from using environmental variables if possible.

  • Each robot pose and other variables must be explicitly defined in the example.

  • The code should be as short and simple as possible, but at the same time follow the same quality standards as the source code (doc strings, type hints, …).

  • The setup of a logger should always be included in the examples.

  • The VorausIndustrialRobotArm should be used as the default robot in the documentation.

  • Boilerplate code to setup the example should be moved to the __main__ function.

If not explicitly needed, line numbers in the code example should be omitted for maintenance reasons. Code snippets can be quoted using the :start-at:, :end-at: or :end-before: parameters. In this case the :dedent: attribute should be used to align the code section to the left.

The complete application example should be added as an admonition, together with a small sentence at the beginning of what the full example does:

:::{admonition} Complete Example for \<Doing Something\>
:class: dropdown

```{literalinclude} /docs_src/developer/how_to_write_trait_docu.py
  :language: Python
```
:::

Complete Example for <Doing Something>

"""A simple example on how to <do something>."""

from math import radians
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    JointPose,
    LifecycleTrait,
    MovePTPTrait,
    VorausIndustrialRobotArm,
    configure_logging,
)

VORAUS_CORE_HOST = "localhost"
VORAUS_ROBOT_CONTROL_PORT = 48401

HOME = JointPose().from_list(
    [radians(d) for d in [0, -90, 90, -90, -90, 0]]
)


@runtime_checkable
class _RequiredRobotTraits(
    LifecycleTrait,
    MovePTPTrait,
    # <Add all needed traits here>
    Protocol,
): ...


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example application to demonstrate <something>."""
    robot.move_ptp(HOME).result()


if __name__ == "__main__":
    configure_logging()
    robot = VorausIndustrialRobotArm()
    with robot.connect(VORAUS_CORE_HOST, VORAUS_ROBOT_CONTROL_PORT):
        robot.enable()
        run_my_application(robot)

Definition of the <Trait> Methods

At the end, add an admonition of the trait definition which contains the described methods, as shown below:

:::{admonition} Definition of the `<Some Trait>`
:class: dropdown

```{eval-rst}
.. autoprotocol:: docs.docs_src.developer.some_trait.SomeTrait
    :member-order: bysource
    :noindex:
```
:::

which will be rendered as:

Definition of the <Some Trait>

protocol SomeTrait

Trait to do something.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod first_method(some_input, some_other_input=5.0)

Does something.

Parameters:

  • some_input (str) – Input that is needed for something.

  • some_other_input (float) – Some other input.

Return type:

None

abstractmethod second_method()

Does something and returns.

Return type:

bool

Returns:

Some boolean value.