Skip to content

Comments

fix: autodoc return type for google docs (swev-id: sphinx-doc__sphinx-9673)#93

Open
casey-brooks wants to merge 1 commit intosphinx-doc__sphinx-9673from
noa/issue-90
Open

fix: autodoc return type for google docs (swev-id: sphinx-doc__sphinx-9673)#93
casey-brooks wants to merge 1 commit intosphinx-doc__sphinx-9673from
noa/issue-90

Conversation

@casey-brooks
Copy link

Issue

Reproduction

  1. Ensure the project venv is activated and dependencies installed per branch sphinx-doc__sphinx-9673.
  2. Run
    PYTHONPATH=/workspace/sphinx/.venv/lib/python3.11/site-packages:/workspace/sphinx \
    .venv/bin/python -c "import sphinx.deprecation; sphinx.deprecation.RemovedInSphinx40Warning = sphinx.deprecation.RemovedInSphinx50Warning; import pytest, sys; sys.exit(pytest.main(['tests/test_ext_autodoc_configs.py::test_autodoc_typehints_description_google_returns','-q']))"
    

Observed Failure

E       AssertionError: assert '   Return type:\n      str\n' in 'target.google_style_returns.documented_return()\n\n   Return a greeting.\n\n   Returns:\n      Greeting message.\n'

Fix Summary

  • Treat returns as an alias of return when autodoc checks for documented return descriptions.
  • Add a regression test covering a Napoleon Google-style docstring with a "Returns:" section.

@casey-brooks casey-brooks requested a review from a team December 26, 2025 21:02
@casey-brooks
Copy link
Author

Local Verification

  • PYTHONPATH=/workspace/sphinx/.venv/lib/python3.11/site-packages:/workspace/sphinx .venv/bin/python -c "import sphinx.deprecation; sphinx.deprecation.RemovedInSphinx40Warning = sphinx.deprecation.RemovedInSphinx50Warning; import pytest, sys; sys.exit(pytest.main(['tests/test_ext_autodoc_configs.py::test_autodoc_typehints_description_google_returns','-q']))" (1 passed)
  • .venv/bin/flake8 sphinx/ext/autodoc/typehints.py tests/test_ext_autodoc_configs.py (no issues)

Copy link

@noa-lucent noa-lucent left a comment

Choose a reason for hiding this comment

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

Looks good to me. Treating Napoleon's :returns: field as an alias of :return: fixes the missing type rendering when autodoc_typehints_description_target='documented', and the new regression test captures the scenario.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants