Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add HTML markup to method/function return typehint #9225

Merged
merged 7 commits into from Jul 11, 2021
Merged

Add HTML markup to method/function return typehint #9225

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
643131a
Add HTML markup to the return type hint.
doerwalter May 13, 2021
cf2d5b3
Rename CSS classes for return type hint HTML markup.
doerwalter May 15, 2021
b079543
Add configuration option html_signaturereturn_icon for the arrow befo…
doerwalter May 16, 2021
6af23a9
Fix typo.
doerwalter May 22, 2021
ac2eb03
Add version info for html_signaturereturn_icon.
doerwalter May 22, 2021
798adc4
Add tests for html_signaturereturn_icon.
doerwalter May 22, 2021
9aedeee
Remove configuration option html_signaturereturn_icon.
doerwalter Jun 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/usage/configuration.rst
View file
Open in desktop
Expand Up @@ -1191,6 +1191,11 @@ that use Sphinx's HTMLWriter class.

.. versionadded:: 3.5

.. confval:: html_signaturereturn_icon
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don't understand why this is needed. Do you want to change the character of the allow?
Adding a new configuration increases the cost of maintenance. So I need to know this is really needed.

Note:

  • Which is better html_signaturereturn_icon and html_signature_return_icon.
  • If we'll determine to add this, testcase is needed.
  • If we'll determine to add this, it will be released as 4.x (maybe 4.1).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've fixed the typo.

Yes, I would like to be able to replace the arrow character.

My reason for this is that I would like to be able to display the function/method signature without the type hints. The type hints should however be displayed when the user hovers over an annotation icon with the mouse. This should work for both the parameter type hints and the return type hints. I would like to use consistent icons for this. For example https://fontawesome.com/icons/question-circle?style=regular for the parameter hint and https://fontawesome.com/icons/arrow-circle-right?style=regular for the return hint.

I find long signatures with type hints confusing. An extreme example from Sphinx (in application.py in Sphinx):

    def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: str,
                 buildername: str, confoverrides: Dict = None,
                 status: IO = sys.stdout, warning: IO = sys.stderr,
                 freshenv: bool = False, warningiserror: bool = False, tags: List[str] = None,
                 verbosity: int = 0, parallel: int = 0, keep_going: bool = False) -> None:

IMHO it's hard to see at first glance what is a parameter name, what is a type annotation and what is a default value (even with syntax highlighting). Without the type annotations this look much better:

    def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides,
                 status=sys.stdout, warning=sys.stderr, freshenv=False, warningiserror=False,
                 tags=None, verbosity=0, parallel=0, keep_going=False):

But I don't want to drop the type annotations completely, because they're useful when you are writing the function call. Fortunately on an HTML page we can have both: short and clear signatures and access to the type hints: By displaying the type hints on demand via a popup/tooltip.

I realize that this currently isn't possible for the parameter hint, but this patch makes it possible for the return hint.

I chose html_signaturereturn_icon for that name, because this matches the name for html_permalinks_icon.

However if we would introduce an icon for the parameter annotation in the future, html_signature_return_icon would make more sense, since we might have html_signature_param_icon too.

I'll start working on a testcase.

OK, I'll add a .. versionadded:: 4.1 to the documentation.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your explanation. I understand it is worthy for you. But, I don't think it's also worthy for other users. Is it possible to change the icon by CSS hack or JS?


A text for prepended to the type hint for the return type of a function or
method. HTML tags are allowed. Default: an wrrow; ``→``
tk0miya marked this conversation as resolved.
Show resolved Hide resolved

.. confval:: html_sidebars

Custom sidebar templates, must be a dictionary that maps document names to
Expand Down
1 change: 1 addition & 0 deletions sphinx/builders/html/__init__.py
View file
Open in desktop
Expand Up @@ -1320,6 +1320,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('html_add_permalinks', UNSET, 'html')
app.add_config_value('html_permalinks', True, 'html')
app.add_config_value('html_permalinks_icon', '¶', 'html')
app.add_config_value('html_signaturereturn_icon', '→', 'html')
app.add_config_value('html_use_index', True, 'html')
app.add_config_value('html_split_index', False, 'html')
app.add_config_value('html_copy_source', True, 'html')
Expand Down
6 changes: 4 additions & 2 deletions sphinx/writers/html.py
View file
Open in desktop
Expand Up @@ -174,10 +174,12 @@ def depart_desc_type(self, node: Element) -> None:
pass

def visit_desc_returns(self, node: Element) -> None:
self.body.append(' → ')
self.body.append(' <span class="sig-return"><span class="sig-return-icon">')
self.body.append(self.config.html_signaturereturn_icon)
self.body.append('</span> <span class="sig-return-typehint">')

def depart_desc_returns(self, node: Element) -> None:
pass
self.body.append('</span></span>')

def visit_desc_parameterlist(self, node: Element) -> None:
self.body.append('<span class="sig-paren">(</span>')
Expand Down
6 changes: 4 additions & 2 deletions sphinx/writers/html5.py
View file
Open in desktop
Expand Up @@ -145,10 +145,12 @@ def depart_desc_type(self, node: Element) -> None:
pass

def visit_desc_returns(self, node: Element) -> None:
self.body.append(' &#x2192; ')
self.body.append(' <span class="sig-return"><span class="sig-return-icon">')
self.body.append(self.config.html_signaturereturn_icon)
self.body.append('</span> <span class="sig-return-typehint">')

def depart_desc_returns(self, node: Element) -> None:
pass
self.body.append('</span></span>')

def visit_desc_parameterlist(self, node: Element) -> None:
self.body.append('<span class="sig-paren">(</span>')
Expand Down