Add Sphinx docs customization for multimethod #1088

lorenzncode · 2022-05-24T03:17:15Z

This adds customization to better handle multimethod in the HTML docs. To resolve #1087.

Now multimethod is handled in a similar way as overload and singledispatch.

codecov · 2022-05-24T03:39:01Z

Codecov Report

Merging #1088 (5d83e3b) into master (a5fadeb) will not change coverage.
The diff coverage is n/a.

❗ Current head 5d83e3b differs from pull request most recent head 3c35d7b. Consider uploading reports for the commit 3c35d7b to get more accurate results

@@           Coverage Diff           @@
##           master    #1088   +/-   ##
=======================================
  Coverage   96.34%   96.34%           
=======================================
  Files          40       40           
  Lines        9533     9533           
  Branches     1259     1259           
=======================================
  Hits         9185     9185           
  Misses        205      205           
  Partials      143      143

Impacted Files	Coverage Δ
cadquery/sketch.py	`96.30% <ø> (ø)`

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more

Handle multimethod class methods in automodule customization Update sphinx pin Update .gitignore for vim

lorenzncode · 2022-06-04T04:17:24Z

Here is an example of the customized autosummary output (API Reference):

It shows ellipsis in place of the input parameters now.

This provides a hint, and following the link, multiple signatures are displayed.

The Parameters field list continues to show a single set of parameters for one of the signatures similar to overloads. The source link is available to show the implementation.

jmwright · 2022-06-06T21:39:03Z

@lorenzncode I think this looks good. Is it ready for review?

lorenzncode · 2022-06-07T01:16:24Z

Yes, this is ready for review. Thanks for taking a look.

jmwright · 2022-06-07T13:19:18Z

@Peque You have done a lot with our Sphinx setup before, do you have the time and interest to take a look at this PR?

@lorenzncode I get the following warning when I generate the docs, are you getting it as well? WARNING: while setting up extension sphinx_autodoc_multimethod: directive 'autosummary' is already registered, it will be overridden

Peque · 2022-06-07T13:25:03Z

@jmwright Not the time, but thanks for the ping! 😊

lorenzncode · 2022-06-08T23:09:55Z

Thanks @jmwright. Yes I reproduced the warning. I've pushed a change to address the warning by setting the override=True flag. Since this is an intentional override, sphinx will no longer issue the warning.

jmwright · 2022-06-09T10:39:05Z

Thanks @lorenzncode

Other than the two other comments I think this PR looks good. I'm not sure who else will review it. @adam-urbanczyk are you available to do it?

dcowden · 2022-06-09T11:27:13Z

@jmwright i can review, I probably can get to it early next week

jmwright · 2022-06-09T11:30:44Z

@dcowden Great thanks!

adam-urbanczyk

LGTM, would it be possible (and not too much work) to generate three parameter lists under each function prototype?

dcowden · 2022-06-14T23:00:23Z

+1

dcowden

Definitely not a sphinx expert here, but looks ok to me

jmwright

@lorenzncode Thanks! Feel free to merge if you think it's ready. You might want to start a new issue for the comment made by @adam-urbanczyk . I think this is a nice stand-alone PR as-is, but that's a possible future change.

jmwright · 2022-06-07T13:02:23Z

doc/ext/sphinx_autodoc_multimethod.py

+                # of inner classes can be documented
+                full_name = modname + "::" + full_name[len(modname) + 1 :]
+            # NB. using full_name here is important, since Documenters
+            #     handle module prefixes slightly differently


Are the extra preceding spaces in this comment intentional?

This extension creates a subclass of sphinx.ext.autodoc.MethodDocumenter overriding method format_signature and a sublcass of sphinx.ext.autosummary.AutoSummary overriding get_items. Actually this comment comes from the original implementation of get_items. I didn't change the formatting other than run black. I would suggest to keep the extra spaces as is to help diff in the future say when checking for compatibility with a new Sphinx release (I'll add a note on maintenance).

jmwright · 2022-06-07T13:08:14Z

cadquery/sketch.py

@@ -782,7 +782,7 @@ def arc(
        forConstruction: bool = False,
    ) -> T:
        """
-        Construct an arc starting at p1, through p2, ending at p3


This was actually added in a fairly recent PR. https://github.com/CadQuery/cadquery/pull/1049/files

What's the reason for removing it?

Right, this was intentionally reverted back to the original docstring. The original docstring has a generic description that is applicable to all of the dispatch methods which is better than a description specific to only one of the methods.

lorenzncode · 2022-06-17T00:25:07Z

LGTM, would it be possible (and not too much work) to generate three parameter lists under each function prototype?

I agree the vertical field list for each prototype would be nice to try. Unfortunately it does not look easy to me.

This PR attempts to bring multimethod support more in line with how Sphinx handles overload and singledispatchmethod where Sphinx supports a list of signatures. This was mostly a matter of identifying multimethod usage and appending to the signature list. Sphinx does not show the Parameter field list for each signature today for say singledispatchmethod so I think more significant customization would be required.

lorenzncode · 2022-06-17T00:51:05Z

Notes on maintenance:

When updating to a newer Sphinx version, test that the extension is working. The extension depends on Sphinx autodoc and autosummary and may require updates depending on changes to Sphinx (there were none from v4.5 to v5.0 so far).

Compare MultimethodAutosummary.get_items, and MethodDocumenter.format_signature with the Sphinx implementation.
The modifications are commented with # -- multimethod customization, # -- end customization.

lorenzncode · 2022-06-17T01:00:58Z

I pushed a minor change to a .gitignore entry added in this PR. If there are no other issues, this is ready to squash and merge.

jmwright · 2022-06-17T01:37:46Z

Thanks @lorenzncode

I re-ran the randomly falling test on Windows and it passed the second time.

adam-urbanczyk · 2022-06-17T05:38:21Z

I agree the vertical field list for each prototype would be nice to try. Unfortunately it does not look easy to me.

This PR attempts to bring multimethod support more in line with how Sphinx handles overload and singledispatchmethod where Sphinx supports a list of signatures. This was mostly a matter of identifying multimethod usage and appending to the signature list. Sphinx does not show the Parameter field list for each signature today for say singledispatchmethod so I think more significant customization would be required.

No worries, thanks for the hard work!

Add Sphinx docs customization for multimethod

7df244d

lorenzncode marked this pull request as draft May 24, 2022 03:51

lorenzncode added 2 commits June 3, 2022 21:14

Merge branch 'master' into sphinx-multimethod

e908945

Customize sphinx autosummary for multimethod

e8f1859

Handle multimethod class methods in automodule customization Update sphinx pin Update .gitignore for vim

lorenzncode marked this pull request as ready for review June 4, 2022 04:16

jmwright self-requested a review June 7, 2022 12:54

Set override=True when adding autosummary directive

66ba29f

jmwright requested a review from dcowden June 9, 2022 14:01

adam-urbanczyk approved these changes Jun 12, 2022

View reviewed changes

dcowden approved these changes Jun 14, 2022

View reviewed changes

jmwright approved these changes Jun 15, 2022

View reviewed changes

Change .gitignore, only ignore hidden .swp

3c35d7b

jmwright merged commit c9d3f1e into CadQuery:master Jun 17, 2022

lorenzncode mentioned this pull request Jul 24, 2022

Docs extra duplicate signature shown for dprism HTML autodoc #1120

Closed

lorenzncode deleted the sphinx-multimethod branch February 26, 2023 17:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Sphinx docs customization for multimethod #1088

Add Sphinx docs customization for multimethod #1088

lorenzncode commented May 24, 2022

codecov bot commented May 24, 2022 •

edited

Loading

lorenzncode commented Jun 4, 2022

jmwright commented Jun 6, 2022

lorenzncode commented Jun 7, 2022

jmwright commented Jun 7, 2022

Peque commented Jun 7, 2022

lorenzncode commented Jun 8, 2022

jmwright commented Jun 9, 2022

dcowden commented Jun 9, 2022

jmwright commented Jun 9, 2022

adam-urbanczyk left a comment

dcowden commented Jun 14, 2022

dcowden left a comment

jmwright left a comment

jmwright Jun 7, 2022

lorenzncode Jun 17, 2022

jmwright Jun 7, 2022

lorenzncode Jun 17, 2022

lorenzncode commented Jun 17, 2022

lorenzncode commented Jun 17, 2022

lorenzncode commented Jun 17, 2022

jmwright commented Jun 17, 2022

adam-urbanczyk commented Jun 17, 2022

Add Sphinx docs customization for multimethod #1088

Add Sphinx docs customization for multimethod #1088

Conversation

lorenzncode commented May 24, 2022

codecov bot commented May 24, 2022 • edited Loading

Codecov Report

lorenzncode commented Jun 4, 2022

jmwright commented Jun 6, 2022

lorenzncode commented Jun 7, 2022

jmwright commented Jun 7, 2022

Peque commented Jun 7, 2022

lorenzncode commented Jun 8, 2022

jmwright commented Jun 9, 2022

dcowden commented Jun 9, 2022

jmwright commented Jun 9, 2022

adam-urbanczyk left a comment

Choose a reason for hiding this comment

dcowden commented Jun 14, 2022

dcowden left a comment

Choose a reason for hiding this comment

jmwright left a comment

Choose a reason for hiding this comment

jmwright Jun 7, 2022

Choose a reason for hiding this comment

lorenzncode Jun 17, 2022

Choose a reason for hiding this comment

jmwright Jun 7, 2022

Choose a reason for hiding this comment

lorenzncode Jun 17, 2022

Choose a reason for hiding this comment

lorenzncode commented Jun 17, 2022

lorenzncode commented Jun 17, 2022

lorenzncode commented Jun 17, 2022

jmwright commented Jun 17, 2022

adam-urbanczyk commented Jun 17, 2022

codecov bot commented May 24, 2022 •

edited

Loading