diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..2b777f9 --- /dev/null +++ b/Makefile @@ -0,0 +1,5 @@ + + +documentation: + pdoc --html -f -o doc --config show_inherited_members=True openscad_py + diff --git a/openscad_py/color.py b/openscad_py/color.py index c7e041e..30b4cd7 100644 --- a/openscad_py/color.py +++ b/openscad_py/color.py @@ -7,8 +7,11 @@ from openscad_py.object_ import Object class Color(Object): + """Represents a color applied to an object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#color + """ - def __init__(self, child: Object, r, g, b, a=1.): + def __init__(self, child: Object, r: float, g: float, b: float, a: float = 1.): self.color = [r, g, b, a] self.child = child @@ -16,4 +19,3 @@ class Color(Object): """Render the object into OpenSCAD code""" return f"color(c=[{','.join([str(c) for c in self.color])}]){{ {self.child.render()} }}" - diff --git a/openscad_py/difference.py b/openscad_py/difference.py index 7a300ce..f8678e1 100644 --- a/openscad_py/difference.py +++ b/openscad_py/difference.py @@ -8,7 +8,9 @@ from openscad_py.collection import Collection class Difference(Object): - """Represents a difference""" + """Represents a difference. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#difference + """ def __init__(self, subject: Object, tool: TUnion[list, Object]): self.subject = subject diff --git a/openscad_py/intersection.py b/openscad_py/intersection.py index 6397a85..0c6ca08 100644 --- a/openscad_py/intersection.py +++ b/openscad_py/intersection.py @@ -8,7 +8,9 @@ from openscad_py.collection import Collection class Intersection(Object): - """Represents an intersection applied to an object (usually a collection of objects)""" + """Represents an intersection applied to an object (usually a collection of objects). + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#intersection + """ def __init__(self, child: TUnion[Object, list]): self.child = Collection.c(child) diff --git a/openscad_py/object_.py b/openscad_py/object_.py index 4f8b825..655fcd8 100644 --- a/openscad_py/object_.py +++ b/openscad_py/object_.py @@ -7,13 +7,14 @@ from openscad_py.point import Point class Object: - """Abstract class for an SCAD object""" + """Base class for an SCAD object. Defines convenience methods to apply transformations.""" def _center(self) -> str: + """Render the `center` flag into string""" return ('true' if self.center else 'false') - def _add(self, obj): - """Add an object, forming a collection""" + def _add(self, obj: 'Object'): + """Add an object, forming a Collection""" from openscad_py.collection import Collection return Collection([self, obj]) @@ -22,64 +23,88 @@ class Object: raise Exception("abstract method") def translate(self, v: TUnion[list, Point]) -> 'Object': - """Apply a translation""" + """Apply a translation and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#translate + """ from openscad_py.translate import Translate return Translate(v=v, child=self) def move(self, v: TUnion[list, Point]) -> 'Object': - """Apply a translation""" + """Apply a translation and return a new object. Synonym of `translate()`""" from openscad_py.translate import Translate return Translate(v=v, child=self) def rotate(self, a, v: TUnion[list, Point]) -> 'Object': - """Apply a rotation""" + """Apply a rotation and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#rotate + """ from openscad_py.rotate import Rotate return Rotate(a=a, v=v, child=self) def scale(self, v: TUnion[list, Point, float]) -> 'Object': - """Apply scaling. Accepts a single float for uniform scaling""" + """Apply scaling and return a new object. Accepts a vector (a Point object or a list of floats) + or a single float for uniform scaling. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#scale + """ from openscad_py.scale import Scale return Scale(v=v, child=self) def color(self, r, g, b, a=1.) -> 'Object': - """Apply a color""" + """Apply a color and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#color + """ from openscad_py.color import Color return Color(r=r, g=g, b=b, a=a, child=self) def extrude(self, height, convexity = 10, center: bool = False) -> 'Object': - """Apply a linear extrusion, - If center is false the linear extrusion Z range is from 0 to height; if it is true, the range is from -height/2 to height/2.""" + """Apply a linear extrusion and return a new object. + If `center` is false, the linear extrusion Z range is from 0 to height; + if it is true, the range is from -height/2 to height/2. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/2D_to_3D_Extrusion + """ from openscad_py.linear_extrude import LinearExtrude return LinearExtrude(height=height, child=self, convexity=convexity, center=center) def rotate_extrude(self, angle, convexity = 10) -> 'Object': - """Apply a rotational extrusion. For all points x >= 0 must be true.""" + """Apply a rotational extrusion and return a new object. For all points x >= 0 must be true. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/2D_to_3D_Extrusion + """ from openscad_py.rotate_extrude import RotateExtrude return RotateExtrude(angle=angle, child=self, convexity=convexity) def radial_offset(self, r): - """A new 2d interior or exterior outline from an existing outline""" + """Return a new 2D interior or exterior outline from an existing outline. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#offset + """ from openscad_py.radial_offset import RadialOffset return RadialOffset(r=r, child=self) def delta_offset(self, delta, chamfer=False): - """A new 2d interior or exterior outline from an existing outline""" + """Return a new 2D interior or exterior outline from an existing outline. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#offset + """ from openscad_py.delta_offset import DeltaOffset return DeltaOffset(delta=delta, child=self, chamfer=chamfer) def diff(self, tool: TUnion[list, 'Object']) -> 'Object': - """Remove from the object using a difference operator""" + """Remove from the object using a difference operator, and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#difference + """ from openscad_py.difference import Difference return Difference(subject=self, tool=tool) def union(self, objects: TUnion[list, 'Object']) -> 'Object': - """Form the union of self and an object or list of objects""" + """Form the union of self and an object or list of objects, and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#union + """ from openscad_py.union import Union from openscad_py.collection import Collection return Union(child=Collection.c(objects)._add(self)) def intersection(self, objects: TUnion[list, 'Object']) -> 'Object': - """Get the intersection of self and an object of list of objects""" + """Get the intersection of self and an object of list of objects, and return a new object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#intersection + """ from openscad_py.intersection import Intersection from openscad_py.collection import Collection return Intersection(child=Collection.c(objects)._add(self)) diff --git a/openscad_py/rotate.py b/openscad_py/rotate.py index 76a4744..8c714c9 100644 --- a/openscad_py/rotate.py +++ b/openscad_py/rotate.py @@ -8,7 +8,9 @@ from openscad_py.object_ import Object class Rotate(Object): - """Represents a rotation transformation applied to an object""" + """Represents a rotation transformation applied to an object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#rotate + """ def __init__(self, a, v: TUnion[list, Point], child: Object): self.a = a diff --git a/openscad_py/scale.py b/openscad_py/scale.py index 42533e1..d4fe0eb 100644 --- a/openscad_py/scale.py +++ b/openscad_py/scale.py @@ -8,6 +8,9 @@ from openscad_py.object_ import Object class Scale(Object): + """Represents a scale transformation applied to an object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#scale + """ def __init__(self, v: TUnion[list, Point, float, int], child: Object): if isinstance(v, float) or isinstance(v, int): diff --git a/openscad_py/translate.py b/openscad_py/translate.py index c18c1da..22f6330 100644 --- a/openscad_py/translate.py +++ b/openscad_py/translate.py @@ -8,7 +8,9 @@ from openscad_py.object_ import Object class Translate(Object): - """Represents a translation transformation applied to an object""" + """Represents a translation transformation applied to an object. + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#translate + """ def __init__(self, v: TUnion[list, Point], child: Object): self.v = Point.c(v) diff --git a/openscad_py/union.py b/openscad_py/union.py index e3aa067..bc6b9c5 100644 --- a/openscad_py/union.py +++ b/openscad_py/union.py @@ -9,7 +9,9 @@ from openscad_py.collection import Collection class Union(Object): - """Represents a union applied to an object (usually a collection of objects)""" + """Represents a union applied to an object (usually a collection of objects). + See https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling#union + """ def __init__(self, child: TUnion[Object, list]): self.child = Collection.c(child)