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