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

simplify function sigs in documentation #319

Draft
wants to merge 3 commits into
base: develop
Choose a base branch
from
Draft

simplify function sigs in documentation #319

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
70a392e
simplify function sigs in documentation
j-emberton Oct 7, 2024
1573b41
remove tuple import
j-emberton Oct 7, 2024
8b35925
moved type hints from signature to params
j-emberton Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
from datetime import datetime

import sphinxcontrib.bibtex.plugin
import tuple
Copy link
Collaborator

Choose a reason for hiding this comment

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

@j-emberton This breaks the docs build - we can just the generic for typing so I think can delete this line.

Copy link
Collaborator Author

@j-emberton j-emberton Oct 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I think its this line:

signature = signature.replace("~numpy.ndarray", "ndarray")

They seem to build ok locally when I comment these lines out.

If we want we can either tolerate the extranumpy., or try and find a work around to get the best presentation.

Copy link
Collaborator

@davidorme davidorme Oct 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

This line is definitely failing it on my machine and RTD:

➜  docs git:(262-incorrect-argument-types--docs) ✗ make html 
Running Sphinx v7.4.7

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/Users/dorme/Library/Caches/pypoetry/virtualenvs/pyrealm-QywIOHcp-py3.11/lib/python3.11/site-packages/sphinx/config.py", line 529, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dorme/Research/REALM/pyrealm/docs/source/conf.py", line 16, in <module>
    import tuple
ModuleNotFoundError: No module named 'tuple'

make: *** [html] Error 2

If I delete that line, I get a "successful" build: no errors but 201 warnings! A lot of those are something going wrong with the simplify_type_hints function.

WARNING: error while formatting signature for pyrealm.constants: Handler <function simplify_type_hints at 0x105fbcd60> for event 'autodoc-process-signature' threw an exception (exception: simplify_type_hints() takes 2 positional arguments but 7 were given)

from sphinxcontrib.bibtex.style.referencing import BracketStyle
from sphinxcontrib.bibtex.style.referencing.author_year import AuthorYearReferenceStyle

Expand Down Expand Up @@ -177,6 +178,15 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
# - Group members by type not alphabetically
autodoc_member_order = "groupwise"

# Control how type hints are shown in the generated documentation
autodoc_typehints_format = "short" # Use short format for type hints

# Use unqualified names for types (i.e., without the module prefix)
python_use_unqualified_type_names = True

napoleon_use_param = False # Do not show type hints in function signatures
napoleon_use_rtype = False # Do not show return types in function signatures

bibtex_bibfiles = ["refs.bib"]

# Add any paths that contain templates here, relative to this directory.
Expand Down Expand Up @@ -216,6 +226,23 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
html_static_path = ["_static"]


# Custom logic to simplify specific types in type annotations
def simplify_type_hints(signature: str, return_annotation: str) -> tuple[str, str]:
"""Simplifies function signatures for documentation."""
# Replace verbose numpy type hints with simpler versions
if signature:
signature = signature.replace("~numpy.ndarray", "ndarray")
signature = signature.replace("~typing.Any", "Any")
signature = signature.replace("~numpy.dtype[~numpy.float32]", "float32")
if return_annotation:
return_annotation = return_annotation.replace("~numpy.ndarray", "ndarray")
return_annotation = return_annotation.replace("~typing.Any", "Any")
return_annotation = return_annotation.replace(
"~numpy.dtype[~numpy.float32]", "float32"
)
return signature, return_annotation


def setup(app): # type: ignore
"""Use setup to remove .ipynb from sources.

Expand All @@ -224,3 +251,5 @@ def setup(app): # type: ignore
"""
# Ignore .ipynb files
app.registry.source_suffix.pop(".ipynb", None)
# Connect the event to modify the type hints
app.connect("autodoc-process-signature", simplify_type_hints)
Loading