Formatting Guide

This section is only for myself, because of the long pauses between develop iterations, I often forget to be consistent in documentation formatting.

Documentation is written with Sphinx and reSturcturedText.

Started integration of documentation into source code and using autodoc features of Sphinx wherever useful.

Sphinx theme provided by Read the Docs :

pip install sphinx-rtd-theme

guide — Example module

guide.example_func(a: int, b: str, test: str = None, flag: bool = True) → None

Parameters a and b are positional arguments, argument test defaults to None and flag to True. Set a to 70 and b to “x” as an example. Inline code examples example_func(70, 'x') or simple example_func(70, "x")

• arguments: a, b, test and flags

• literal number values: 1, 2 … 999

• literal string values: “a String”

• literal tags: (5, “F000”)

• inline code: call a example_func(x)

• Python keywords: None, True, False, tuple, list, dict, str, int, float

• Exception classes: DXFAttributeError

class guide.ExampleCls(**kwargs)

The ExampleCls constructor accepts a number of optional keyword arguments. Each keyword argument corresponds to an instance attribute, so for example

e = ExampleCls(flag=True)

flag

This is the attribute flag.

set_axis(axis)

axis as (x, y, z) tuple

Args:

axis: (x, y, z) tuple

example_method(flag: bool = False) → None

Method example_method() of class ExampleCls

Text Formatting

DXF version

DXF R12 (AC1009), DXF R2004 (AC1018)

DXF Types

DXF types are always written in uppercase letters but without further formatting: DXF, LINE, CIRCLE

(internal API)

Marks methods as internal API, gets no public documentation.

(internal class)

Marks classes only for internal usage, gets not public documentation.

Spatial Dimensions

2D and 3D with an uppercase letter D

Axis

x-axis, y-axis and z-axis

Planes

xy-plane, xz-plane, yz-plane

Layouts

modelspace, paperspace [layout], block [layout]

Extended Entity Data

AppData, XDATA, embedded object, APPID