From 89d5f1322173ad19c93def2d3664829ff0e8965f Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Fri, 5 Nov 2021 20:33:17 -0400 Subject: [PATCH 1/5] Fix doc issue where parameters could be listed twice in the method description * Remove sphinx extension sphinx_autodoc_typehints * Update sphinx pin to version 4.2.0 * Show typehints in both signature and description --- doc/conf.py | 4 ++-- environment.yml | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index e7406bf5a..beba9fff4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,14 +40,14 @@ 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" # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/environment.yml b/environment.yml index 922a1d8eb..aec32eef1 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.2.0 - sphinx_rtd_theme - - sphinx-autodoc-typehints - black=19.10b0 - mypy - codecov From 542c110f6bcecf747ed33741afb50b2816c421d4 Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Sat, 20 Nov 2021 17:54:06 -0500 Subject: [PATCH 2/5] Move self to top of Parameter list in method documentation * Update sphinx pin to version 4.3.0 --- doc/conf.py | 21 +++++++++++++++++++++ environment.yml | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index beba9fff4..8d80ba4c0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -288,3 +288,24 @@ 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.connect("autodoc-process-docstring", process_docstring_insert_self) + diff --git a/environment.yml b/environment.yml index 81d18e794..bbd317889 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - ipython - ocp=7.5.1 - pyparsing>=2.1.9 - - sphinx=4.2.0 + - sphinx=4.3.0 - sphinx_rtd_theme - black=19.10b0 - mypy From 8613ce1ec3fd7778c3c9d8ed10e93a7566adb4d1 Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Sat, 20 Nov 2021 18:24:59 -0500 Subject: [PATCH 3/5] Fix black formatting --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 8d80ba4c0..bedcf52a7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -305,7 +305,7 @@ def process_docstring_insert_self(app, what, name, obj, options, lines): lines.insert(i, ":param self:") break + def setup(app): app.connect("autodoc-process-docstring", process_docstring_insert_self) - From d62eb82d22c4f5b72b411f0ec442bb2100b8ce4e Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Sun, 28 Nov 2021 12:21:32 -0500 Subject: [PATCH 4/5] * Update sphinx pin to version 4.3.1 --- doc/conf.py | 5 +---- environment.yml | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index bedcf52a7..61ae04885 100644 --- a/doc/conf.py +++ b/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. @@ -308,4 +304,5 @@ def process_docstring_insert_self(app, what, name, obj, options, lines): def setup(app): + app.add_css_file("tables.css") app.connect("autodoc-process-docstring", process_docstring_insert_self) diff --git a/environment.yml b/environment.yml index bbd317889..64fc9bc77 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - ipython - ocp=7.5.1 - pyparsing>=2.1.9 - - sphinx=4.3.0 + - sphinx=4.3.1 - sphinx_rtd_theme - black=19.10b0 - mypy From 9b13724ef3e7667c24b464e33432f355ade63d7c Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Fri, 25 Mar 2022 21:34:13 -0400 Subject: [PATCH 5/5] * Update sphinx pin to version 4.4.0 * autodoc_typehints_format = "short" --- doc/conf.py | 1 + doc/primer.rst | 3 ++- environment.yml | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 61ae04885..df27c168a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -44,6 +44,7 @@ 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"] diff --git a/doc/primer.rst b/doc/primer.rst index d1d87256e..028f971a8 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 64fc9bc77..0cf16eadc 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - ipython - ocp=7.5.1 - pyparsing>=2.1.9 - - sphinx=4.3.1 + - sphinx=4.4.0 - sphinx_rtd_theme - black=19.10b0 - mypy