py domain: Allow to make a style for arguments of functions and methods #6990

tk0miya · 2020-01-04T10:36:53Z

Feature or Bugfix

Feature

Purpose

refs: More fine-grained highlighting of parameters in function signatures #6417
This tries to parse function signatures with AST parser
If succeeded, it wraps argument name, annotation and default value with inline node to decorate by CSS or LaTeX macros.
~~This adds new dependency: cached-property. So I'll merge this into master branch.~~

Remaining tasks

tests
~~documentation~~
design
- ~~additional nodes is needed?~~ => No.
- style name is appropriate?

CHANGES

sphinx/domains/python.py

sphinx/pycode/function.py

sphinx/util/inspect.py

Thom1729 · 2020-01-04T16:50:53Z

Would it make sense to wrap each argument in an element? Something like:

def join(*items: List, delimiter: str = ''):

<span class="argument">
    <span class="argument-sigil">*</span><span class="argument-name">items</span>
    : <span class="annotation">List</span>
</span>,
<span class="argument">
    <span class="argument-name">delimiter</span>
    : <span class="annotation">str</span>
    = <span class="default-value">''</span>
</span>

This way, you could apply CSS to the entire argument, e.g. to prefer line breaks between arguments rather than within them.

tk0miya · 2020-01-06T15:27:47Z

Now HTML writer use <em> to wrap each argument. +1 for changing it to <span> tag :-)

jakobandersen · 2020-01-06T15:56:42Z

Unfortunately I have not had time to take a closer look at this, so the following may be redundant.
The need for styling declarations is there in almost every domain so it would be nice if this PR does not exclude a general solution, or reserves generic CSS class names for the Python domain. For example, a generic CSS class argument-name should be used to style across all domains and py-argument-name should be used to apply styling to Python declarations only.
As explored and discussed a bit in #4289, one approach for the styling categories is to reuse (and refine) what is already in Pygments. Note that it should be possible to set the theme for declarations independently of the Pygments theme used for code snippets.

sphinx/domains/python.py

shimizukawa · 2020-01-11T07:33:41Z

I reviewed the doctree structure. I think it is enough to use the desc_parameter node. I don't think we need to add nodes for argument names or type names. So, LGTM.

eric-wieser · 2020-01-11T13:28:26Z

It would be neat if sphinx could parse a type annotation like MyCollection[MyType] into links to both MyCollection and MyType, but I think that should be left for a separate patch.

tk0miya · 2020-02-13T07:30:16Z

The need for styling declarations is there in almost every domain so it would be nice if this PR does not exclude a general solution, or reserves generic CSS class names for the Python domain.

It is better to surround these element by domain-classed element. It helps to choose individual element by CSS selector like dl.py.function > .argument-name. I'll work for it in another PR.

jakobandersen · 2020-02-13T09:38:46Z

It is better to surround these element by domain-classed element. It helps to choose individual element by CSS selector like dl.py.function > .argument-name. I'll work for it in another PR.

Good point, and nice solution. That probably also minimizes the size of the output.

sphinx/domains/python.py

tk0miya · 2020-02-14T18:02:56Z

I think some discussion points are still remained.

CSS rules (refs: Flexible styling of declarations #4289)
DOM structure

To concentrate these points, I'm going to make another PR for signature parser based on this PR. I think it makes this PR simple.

tk0miya · 2020-02-23T17:06:47Z

Just updated. ready for review now!

tk0miya · 2020-02-23T17:09:45Z

sphinx/addnodes.py

@@ -174,6 +174,31 @@ class desc_content(nodes.General, nodes.Element):
    """


+class desc_sig_element(nodes.inline):


I added desc_sig_element and children to realize pygments based inline text decorator (see #4289).
But I also added SigElementFallbackTransform to support old translators. It helps to render these nodes as simple inline node in old translators.
It means this does not break compatibility! I confirmed working fine with docxbuilder on my local.

sphinx/domains/python.py

tk0miya · 2020-02-23T17:11:23Z

sphinx/domains/python.py

            else:
-                node += nodes.Text('=' + str(param.default))
+                node += addnodes.desc_sig_operator('', '=')
+            node += nodes.inline('', param.default, classes=['default_value'])


I can't find proper toke name from pygments. So I used inline node for default value. Is there good idea?
https://github.com/pygments/pygments/blob/master/pygments/token.py

I have no idea...

tk0miya · 2020-03-06T14:37:51Z

Is there any comments? If none, I'll merge this soon. The feature freeze period for 3.x will come soon.

shimizukawa

LGTM!

shimizukawa · 2020-03-07T09:02:31Z

sphinx/domains/python.py

            else:
-                node += nodes.Text('=' + str(param.default))
+                node += addnodes.desc_sig_operator('', '=')
+            node += nodes.inline('', param.default, classes=['default_value'])


I have no idea...

…ds (refs: sphinx-doc#6417)

tk0miya · 2020-03-14T08:42:08Z

Merged. Thank you for reviewing!

tk0miya added type:enhancement enhance or introduce a new feature domains:py labels Jan 4, 2020

tk0miya added this to the 3.0.0 milestone Jan 4, 2020

tk0miya mentioned this pull request Jan 4, 2020

More fine-grained highlighting of parameters in function signatures #6417

Closed

tk0miya force-pushed the function_signature branch 3 times, most recently from 40c828d to 485e881 Compare January 4, 2020 13:32

tk0miya commented Jan 4, 2020

View reviewed changes

tk0miya force-pushed the function_signature branch from 485e881 to b2c431b Compare January 4, 2020 13:39

tk0miya mentioned this pull request Jan 4, 2020

Close #2755: autodoc: Support type_comment style annotation #6984

Merged

eric-wieser reviewed Jan 4, 2020

View reviewed changes

sphinx/pycode/function.py Outdated Show resolved Hide resolved

eric-wieser reviewed Jan 4, 2020

View reviewed changes

sphinx/pycode/function.py Outdated Show resolved Hide resolved

eric-wieser reviewed Jan 4, 2020

View reviewed changes

sphinx/pycode/function.py Outdated Show resolved Hide resolved

tk0miya force-pushed the function_signature branch 2 times, most recently from 8e7484c to 03bdb25 Compare January 4, 2020 15:01

eric-wieser reviewed Jan 4, 2020

View reviewed changes

sphinx/util/inspect.py Outdated Show resolved Hide resolved

tk0miya force-pushed the function_signature branch 2 times, most recently from 1f1b7d5 to a44d6f9 Compare January 8, 2020 16:28

eric-wieser reviewed Jan 8, 2020

View reviewed changes

sphinx/domains/python.py Outdated Show resolved Hide resolved

tk0miya mentioned this pull request Jan 10, 2020

refactor: Simplify stringify_signature() #7013

Merged

tk0miya mentioned this pull request Feb 9, 2020

python: Improve formatting of signatures with type hints #5868

Closed

tk0miya mentioned this pull request Feb 13, 2020

Add CSS class indicating its domain for each desc node #7144

Closed

tk0miya force-pushed the function_signature branch from a44d6f9 to 9906a18 Compare February 14, 2020 15:45

tk0miya force-pushed the function_signature branch from 9906a18 to 3eabd86 Compare February 14, 2020 17:52

tk0miya commented Feb 14, 2020

View reviewed changes

sphinx/domains/python.py Outdated Show resolved Hide resolved

tk0miya mentioned this pull request Feb 14, 2020

py domain: Use AST parser to convert signature to doctree #7155

Merged

tk0miya force-pushed the function_signature branch from 3eabd86 to 343bc8e Compare February 14, 2020 18:14

tk0miya force-pushed the function_signature branch from 343bc8e to 19feb1b Compare February 22, 2020 07:21

tk0miya changed the base branch from master to 3.x February 22, 2020 07:37

tk0miya force-pushed the function_signature branch 4 times, most recently from 2f40dda to 5dabbf9 Compare February 23, 2020 16:55

tk0miya marked this pull request as ready for review February 23, 2020 17:06

tk0miya commented Feb 23, 2020

View reviewed changes

tk0miya requested review from shimizukawa and jakobandersen February 23, 2020 17:14

tk0miya force-pushed the function_signature branch from 5dabbf9 to c3cc0d5 Compare February 29, 2020 14:38

shimizukawa approved these changes Mar 7, 2020

View reviewed changes

Add desc_sig_element and inherited nodes

89c446e

tk0miya force-pushed the function_signature branch from 99a7386 to fa95257 Compare March 14, 2020 07:50

py domain: Allow to make a style for arguments of functions and metho…

50cf68e

…ds (refs: sphinx-doc#6417)

tk0miya force-pushed the function_signature branch from fa95257 to 50cf68e Compare March 14, 2020 07:56

tk0miya merged commit 5c0d043 into sphinx-doc:3.x Mar 14, 2020

tk0miya deleted the function_signature branch March 14, 2020 08:42

jakobandersen mentioned this pull request Mar 20, 2021

Flexible declaration styling #9023

Merged

github-actions bot locked as resolved and limited conversation to collaborators Aug 2, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

py domain: Allow to make a style for arguments of functions and methods #6990

py domain: Allow to make a style for arguments of functions and methods #6990

tk0miya commented Jan 4, 2020 •

edited

Thom1729 commented Jan 4, 2020

tk0miya commented Jan 6, 2020

jakobandersen commented Jan 6, 2020

shimizukawa commented Jan 11, 2020

eric-wieser commented Jan 11, 2020

tk0miya commented Feb 13, 2020

jakobandersen commented Feb 13, 2020

tk0miya commented Feb 14, 2020

tk0miya commented Feb 23, 2020

tk0miya Feb 23, 2020

shimizukawa Mar 7, 2020

tk0miya Feb 23, 2020

shimizukawa Mar 7, 2020

tk0miya commented Mar 6, 2020

shimizukawa left a comment

shimizukawa Mar 7, 2020

tk0miya commented Mar 14, 2020

		@@ -174,6 +174,31 @@ class desc_content(nodes.General, nodes.Element):
		"""


		class desc_sig_element(nodes.inline):

py domain: Allow to make a style for arguments of functions and methods #6990

py domain: Allow to make a style for arguments of functions and methods #6990

Conversation

tk0miya commented Jan 4, 2020 • edited

Feature or Bugfix

Purpose

Remaining tasks

Thom1729 commented Jan 4, 2020

tk0miya commented Jan 6, 2020

jakobandersen commented Jan 6, 2020

shimizukawa commented Jan 11, 2020

eric-wieser commented Jan 11, 2020

tk0miya commented Feb 13, 2020

jakobandersen commented Feb 13, 2020

tk0miya commented Feb 14, 2020

tk0miya commented Feb 23, 2020

tk0miya Feb 23, 2020

Choose a reason for hiding this comment

shimizukawa Mar 7, 2020

Choose a reason for hiding this comment

tk0miya Feb 23, 2020

Choose a reason for hiding this comment

shimizukawa Mar 7, 2020

Choose a reason for hiding this comment

tk0miya commented Mar 6, 2020

shimizukawa left a comment

Choose a reason for hiding this comment

shimizukawa Mar 7, 2020

Choose a reason for hiding this comment

tk0miya commented Mar 14, 2020

tk0miya commented Jan 4, 2020 •

edited