Merge branch 'master' into sketch-distribute

Author: lorenzncode

doc/conf.py

@@ -27,10 +27,6 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 
-def setup(app):
-    app.add_css_file("tables.css")
-
-
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -40,14 +36,15 @@ def setup(app):
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
     "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
     "cadquery.cq_directive",
     "sphinx.ext.mathjax",
 ]
 
-always_document_param_types = True
+autodoc_typehints = "both"
+autodoc_typehints_description_target = "all"
+autodoc_typehints_format = "short"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -288,3 +285,25 @@ def setup(app):
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
+
+
+def process_docstring_insert_self(app, what, name, obj, options, lines):
+    """
+    Insert self in front of documented params for instance methods
+    """
+
+    if (
+        what == "method"
+        and getattr(obj, "__self__", None) is None
+        and "self" in obj.__annotations__
+    ):
+        for i, dstr in enumerate(lines):
+            if dstr.startswith(":param"):
+                lines.insert(i, ":param self:")
+                break
+
+
+def setup(app):
+
+    app.add_css_file("tables.css")
+    app.connect("autodoc-process-docstring", process_docstring_insert_self)

doc/primer.rst

@@ -1,6 +1,7 @@
 .. _3d_cad_primer:
 
 .. _cadquery_concepts:
+
 CadQuery Concepts
 ===================================
 
@@ -274,7 +275,7 @@ knowledge of the different C++ libraries to be able to achieve what you want. To
   The package name of any class is written at the top of the documentation page. Often it's written in the class name itself as a prefix.
 
 Going back and forth between the APIs
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 While the 3 APIs provide 3 different layer of complexity and functionality you can mix the 3 layers as you wish.
 Below is presented the different ways you can interact with the different API layers.

environment.yml

@@ -8,9 +8,8 @@ dependencies:
   - ipython
   - ocp=7.5.1
   - pyparsing>=2.1.9
-  - sphinx=3.2.1
+  - sphinx=4.4.0
   - sphinx_rtd_theme
-  - sphinx-autodoc-typehints
   - black=19.10b0
   - mypy
   - codecov