From ee90f2ce28a6e946b039b0a585518e31d9979c8a Mon Sep 17 00:00:00 2001
From: Lorenz <hello@lorenz.space>
Date: Sat, 26 Mar 2022 09:46:09 -0400
Subject: [PATCH] Fix doc issue where parameters listed twice in description
 (#916)

* Update sphinx pin to version 4.4.0
* Remove sphinx extension sphinx_autodoc_typehints
---
 doc/conf.py     | 31 +++++++++++++++++++++++++------
 doc/primer.rst  |  3 ++-
 environment.yml |  3 +--
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index e7406bf5..df27c168 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -27,10 +27,6 @@ import cadquery
 # 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 @@ texinfo_documents = [
 
 # 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)
diff --git a/doc/primer.rst b/doc/primer.rst
index d1d87256..028f971a 100644
--- a/doc/primer.rst
+++ b/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.
diff --git a/environment.yml b/environment.yml
index e92fe405..0cf16ead 100644
--- a/environment.yml
+++ b/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