Merge pull request #17 from gumyr/dev

ReadtheDocs

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+# Build from the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/chain.rst

@@ -0,0 +1,92 @@
+
+####################################
+chain - a parametric chain generator
+####################################
+A chain wrapped around a set of sprockets can be generated with the :ref:`Chain<chain>` class by providing
+the size and locations of the sprockets, how the chain wraps and optionally the chain parameters.
+
+For example, one can create the chain for a bicycle with a rear deraileur as follows:
+
+.. code-block:: python
+
+	import cadquery as cq
+	import cq_warehouse.chain as Chain
+
+	derailleur_chain = Chain(
+	    spkt_teeth=[32, 10, 10, 16],
+	    positive_chain_wrap=[True, True, False, True],
+	    spkt_locations=[
+	        (0, 158.9 * MM, 50 * MM),
+	        (+190 * MM, 0, 50 * MM),
+	        (+190 * MM, 78.9 * MM, 50 * MM),
+	        (+205 * MM, 158.9 * MM, 50 * MM)
+	    ]
+	)
+	if "show_object" in locals():
+	    show_object(derailleur_chain.cq_object, name="derailleur_chain")
+
+The chain is created on the XY plane (methods to move the chain are described below)
+with the sprocket centers being described by:
+
+* a two dimensional tuple (x,y)
+* a three dimensional tuple (x,y,z) which will result in the chain being created parallel
+  to the XY plane, offset by "z"
+* the cadquery Vector class which will displace the chain by Vector.z
+
+To control the path of the chain between the sprockets, the user must indicate the desired
+direction for the chain to wrap around the sprocket. This is done with the ``positive_chain_wrap``
+parameter which is a list of boolean values - one for each sprocket - indicating a counter
+clock wise or positive angle around the z-axis when viewed from the positive side of the XY
+plane. The following diagram illustrates the most complex chain path where the chain
+traverses wraps from positive to positive, positive to negative, negative to positive and
+negative to negative directions (`positive_chain_wrap` values are shown within the arrows
+starting from the largest sprocket):
+
+.. image:: chain_direction.png
+	:alt: chain direction
+
+.. py:module:: chain
+
+.. _chain:
+
+.. autoclass:: Chain
+	:members: assemble_chain_transmission, make_link
+
+Note that the chain is perfectly tight as it wraps around the sprockets and does
+not support any slack. Therefore, as the chain wraps back around to the first
+link it will either overlap or gap this link - this can be seen in the above
+figure at the top of the largest sprocket. Adjust the locations of the sprockets
+to control this value.
+
+Note that the make_link instance method uses the @cache decorator to greatly improve the rate at
+links can be generated as a chain is composed of many copies of the links.
+
+Once a chain or complete transmission has been generated it can be re-oriented as follows:
+
+.. code-block:: python
+
+	two_sprocket_chain = Chain(
+	    spkt_teeth = [32, 32],
+	    positive_chain_wrap = [True, True],
+	    spkt_locations = [ (-5 * IN, 0), (+5 * IN, 0) ]
+	)
+	relocated_transmission = two_sprocket_chain.assemble_chain_transmission(
+	    spkts = [spkt32.cq_object, spkt32.cq_object]
+	).rotate(axis=(0,1,1),angle=45).translate((20, 20, 20))
+
+===================
+Future Enhancements
+===================
+Two future enhancements are being considered:
+
+#. Non-planar chains - If the sprocket centers contain ``z`` values, the chain
+   would follow the path of a spline between the sockets to approximate the path of
+   a bicycle chain where the front and rear sprockets are not in the same plane.
+   Currently, the ``z`` values of the first sprocket define the ``z`` offset of the
+   entire chain.
+#. Sprocket Location Slots - Typically on or more of the
+   sprockets in a chain transmission will be adjustable to allow the chain to be
+   tight around the sprockets. This could be implemented by allowing the user to
+   specify a pair of locations defining a slot for a given sprocket indicating that
+   the sprocket location should be selected somewhere along this slot to create a
+   perfectly fitting chain.

docs/conf.py

@@ -0,0 +1,93 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+cq_warehouse_path = os.path.dirname(os.path.abspath(os.getcwd()))
+source_files_path = os.path.join(cq_warehouse_path, "src/cq_warehouse")
+sys.path.insert(0, source_files_path)
+sys.path.append(os.path.abspath("sphinxext"))
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath("../"))
+
+# -- Project information -----------------------------------------------------
+
+project = "cq_warehouse"
+copyright = "2022, Gumyr"
+author = "Gumyr"
+
+# The full version, including alpha/beta/rc tags
+with open(os.path.join(cq_warehouse_path, "setup.cfg")) as f:
+    setup_cfg = f.readlines()
+for line in setup_cfg:
+    if "version =" in line:
+        release = line.split("=")[1].strip()
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.doctest",
+]
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_use_keyword = True
+napoleon_custom_sections = None
+
+
+autodoc_typehints = ["description"]
+# autodoc_typehints = ["both"]
+autodoc_mock_imports = ["cadquery", "pkg_resources", "OCP"]
+
+# Sphinx settings
+add_module_names = False
+python_use_unqualified_type_names = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/drafting.rst

@@ -0,0 +1,73 @@
+
+.. _drafting:
+
+#################################
+drafting - model-based definition
+#################################
+A class used to document cadquery designs by providing three methods that place
+the dimensions and notes right on the 3D model.
+
+For example:
+
+.. code-block:: python
+
+	import cadquery as cq
+	from cq_warehouse.drafting import Draft
+
+	# Import an object to be dimensioned
+	mystery_object = cq.importers.importStep("mystery.step")
+
+	# Create drawing instance with appropriate settings
+	metric_drawing = Draft(decimal_precision=1)
+
+	# Create an extension line from corners of the part
+	length_dimension_line = metric_drawing.extension_line(
+	    object_edge=mystery_object.faces("<Z").vertices("<Y").vals(),
+	    offset=10.0,
+	    tolerance=(+0.2, -0.1),
+	)
+
+	if "show_object" in locals():
+	    show_object(mystery_object, name="mystery_object")
+	    show_object(length_dimension_line, name="length_dimension_line")
+
+
+To illustrate some of the capabilities of the drafting package, a set of
+dimension lines, extension lines and callouts were applied to a CadQuery part
+with no prior knowledge of any of the dimensions:
+
+.. image:: drafting_example.png
+	:alt: drafting
+
+One could define three instances of the Draft class, one for each of the XY, XZ
+and YZ planes and generate a set of dimensions on each one. By enabling one of
+these planes at a time and exporting svg images traditional drafting documents
+can be generated.
+
+When generating dimension lines there are three possibilities depending on the
+measurement and Draft attributes (described below):
+
+#. The label text (possibly including units and tolerances) and arrows fit within the measurement,
+#. The label text but not the arrows fit within the measurement, or
+#. Neither the text nor the arrows fit within the measurements.
+
+Cases 1 and 2 are shown in the above example. In case 3, the label will be attached to one of the external arrows.
+
+These three possibilities are illustrated below with both linear and arc extension lines:
+
+.. image:: drafting_types.png
+	:alt: drafting
+
+Note that type 3b can only be created by disabling the end arrow - see the arrows parameter below.
+
+To help ease use, a new CadQuery type called ``PathDescriptor`` has been created which is defined as:
+``Union[Wire, Edge, list[Union[Vector, Vertex, tuple[float, float, float]]]`` i.e. a list of points or
+CadQuery edge or wire either extracted from a part or created by the user.
+
+The Draft class contains a set of attributes used to describe subsequent
+dimension_line(s), extension_line(s) or callout(s). The full list is as follows:
+
+.. py:module:: drafting
+
+.. autoclass:: Draft
+	:members: dimension_line, extension_line, callout

docs/environment.yaml

@@ -0,0 +1,10 @@
+name: docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - sphinx
+  - nbsphinx
+  - pip:
+    - sphinx_rtd_theme
+    - git+https://github.com/gumyr/cq_warehouse.git#egg=cq_warehouse