-
-
Notifications
You must be signed in to change notification settings - Fork 25
Project Structure
The main directory structure is as follows:
- /docs
- /examples
- /scripts
- /src/cq_warehouse
- /tests
The documentation is located at https://cq-warehouse.readthedocs.io/en/latest/index.html and is largely auto generated from the cq_warehouse source code. All source code should follow the google python style guide which enables the sphinx documentation system to build documentation directly from the comments in the code.
Extensions to the CadQuery classes present a difficulty to the sphinx system as normally classes are defined in a single module, while extensions monkey patches many new (and some existing) CadQuery methods. To cope with this complication, there is a build_extensions_doc.py script (in the scripts directory) that builds a version of extensions.py suitable for sphinx. This allows the auto-generated extensions documentation to look a though it was part of CadQuery documentation itself.
Each cq_warehouse package has a <package>.rst file that contains the documentation for that package. These packages are listed in the index.rst file table of contents. The .rst file is used by the sphinx system to create the documentation in readthedocs and where possible should use constructs like:
.. autoclass:: bearing.Bearing
.. automethod:: Bearing.typesto enable the bulk of the documentation to be kept in python docstrings such that the documentation always represents the current state of the code base.
To aid with understanding how new cq_warehouse features are used there are many examples in this directory.
Project scripts should be located here. Current there are two:
-
build_extensions_doc.pydescribed above, and -
build_cadquery_patch.pywhich creates a patch to CadQuery adding cq_warehouse extensions. Scripts should be designed to operate on Window, MacOS, and Linux OS's where possible.
All of the source code for cq_warehouse is located here, primarily in .py and .csv files. Each cq_warehouse package is contained in a single python file (e.g. bearing.py) where the file/module name becomes the package name (e.g. from cq_warehouse.bearing import SingleRowTaperedRollerBearing). Therefore, module and class names should be selected with care as they are used directly by cq_warehouse users.
All cq_warehouse source code should have unit tests and achieve 95+% coverage. All tests must pass before a new release is created.
Cadquery objects should be created as a class with properties, one of which being cq_object, the CAD object which may be of type Workplane, Solid, Compound etc. A single module may contain many classes or even follow the base class and derived classes pattern (e.g. the fastener and bearing packages). For example (docstrings not shown):
class NewObject:
@property
def cq_object(self):
return self._some_prebuilt_object
def __init__(self,parameter1: type = default, ...)
self.parameter1 = parameter1
...
self._some_prebuilt_object = ...The user would use this NewObject as follows:
from cq_warehouse.stuff import NewObject
new_cad_object = NewObject(10).cq_objectClasses should expose any properties that might help a user work with that object, for example:
screw = SocketHeadCapScrew(
size="M5-0.8", length=20, fastener_type="iso4762", simple=False
)
...
horizonal_beam_locations = [
l
* cq.Location(
cq.Vector(0, 0, -VSLOT_WIDTH + screw.head_height), cq.Vector(1, 0, 0), 180
)
for l in vslot_assembly.fastenerLocations(screw)
]where the screw.head_height property is used to help position parts.
Objects shouldn't use print, show, show_object, debug, export, or other similar methods.