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.

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

Return type for Yield attribute not properly hyperlinked in apidocs #8004

Closed
TheFriendlyCoder opened this issue Jul 24, 2020 · 2 comments
Closed
Labels
Milestone

Comments

@TheFriendlyCoder
Copy link

Describe the bug
Typically when one defines a return value in a method they will use the following syntax:

Returns:
    int:
        some value

When doing so the return type, int in this case, is hyperlinked to the api docs for the appropriate data type (ie: using interphinx).

However, when writing doc strings for generators using the same / similar syntax provided by the Yield attribute, the data type associated with the generator is not appropriately decorated. Taking the previous example code snippet and making a small modification as show below is sufficient to demonstrate the change in behavior:

Yields:
    int:
        some value

The HTML markup produced by this code snippet simply format the data type using custom font formatting based on the theme, but it fails to associate / generate the hyperlink for the API docs for the data type as is done by the Return attribute.

NOTE: I am using the apidocs Sphinx extension to generate the API docs for my projects in case that has any impact on this behavior.

To Reproduce
Steps to reproduce the behavior:


$ git clone git@github.com:TheFriendlyCoder/friendlypins.git
$ cd friendlypins
$ pip install -r requirements.txt
$ tax -e py38-docs
$ open htmldocs/index.html
# Navigate to the docs for the board class (ie: htmldocs/api/friendlypins.board.html#friendlypins.board.Board.pins)

Expected behavior
The data type should be decorated / marked up the same way it appears when using the Return attribute when using the Yield attribute

Your project
https://github.com/TheFriendlyCoder/friendlypins

Screenshots
Example output generated on ReadTheDocs: https://friendlypins.readthedocs.io/en/latest/api/friendlypins.board.html#friendlypins.board.Board.pins

Environment info

  • OS: MacOS
  • Python version: 3.8.0
  • Sphinx version: 3.1.2
  • Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.napoleon, sphinx.ext.intersphinx
  • Extra tools: any web browser (safari, chrome, firefox, IE)

Additional context

@tristanlatr
Copy link

tristanlatr commented Jan 22, 2021

What about introducing a :ytype: field that would specify the type of the yielded values, just as :rtype: ? :)
Then napoleon can use this to link to the type.

tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 23, 2021
…rings

Type definitions in Google style docstrings are rendered as references
when :confval:`napoleon_preprocess_types` enabled.
@tk0miya tk0miya added this to the 3.5.0 milestone Jan 23, 2021
@tk0miya
Copy link
Member

tk0miya commented Jan 23, 2021

I posted #8731 to enhance napoleon_preprocess_types for google style docstrings. It allows to convert type definitions in docstrings automatically.

tk0miya added a commit that referenced this issue Jan 24, 2021
Fix #8004: napoleon_preprocess_types for Google style docstrings
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 14, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

No branches or pull requests

3 participants