Skip to content

fix(docs): remove typehints_formatter. #1012

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(docs): remove typehints_formatter. #1012

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
47 changes: 1 addition & 46 deletions documentation/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,11 @@
import sys
from pathlib import Path
from types import ModuleType
from typing import Any, Optional, TypeVar, Union
from typing import Optional
from unittest import mock

import sphinx.config
import sphobjinv
import tqdm
from jax.typing import ArrayLike
from sphinx_autodoc_typehints import format_annotation as default_format_annotation

# https://docs.github.com/en/actions/learn-github-actions/variables,
# see the "Default environment variables" section
Expand Down Expand Up @@ -78,11 +75,6 @@
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

# pylint: disable=invalid-name
# Fixes ISSUE #561 pending a fix for ISSUE #570
show_warning_types = True
suppress_warnings = ["config.cache"]
# pylint: enable=invalid-name

# sphinx extensions
extensions = [
Expand Down Expand Up @@ -216,50 +208,13 @@
("py:class", r"jaxtyping\.Shaped\[Array, '.*']"),
]

autodoc_custom_types: dict[Any, str] = { # Specify custom types for autodoc_type_hints
ArrayLike: ":data:`~jax.typing.ArrayLike`",
}

# custom references for tqdm, which does not support intersphinx
tqdm_refs: dict[str, dict[str, str]] = {
"py:class": {
"tqdm.tqdm": "tqdm/#tqdm-objects",
}
}


def typehints_formatter(
annotation: Any, config: sphinx.config.Config
) -> Union[str, None]:
"""
Properly replace custom type aliases.

:param annotation: The type annotation to be processed.
:param config: The current configuration being used.
:returns: A string of reStructured text (e.g. :py:class:`something`) or None to fall
back to the default.

This function is called on each type annotation that Sphinx processes.
The following steps occur:

1. Check if the annotation is a TypeVar. If so, replace it with its "bound" type
for clarity in the docs. If not, then replace it with typing.Any.
2. Check whether a specific Sphinx string has been defined in autodoc_custom_types.
If so, return that.
3. If not, then return None, which uses thee default formatter.

See https://github.com/tox-dev/sphinx-autodoc-typehints?tab=readme-ov-file#options
for specification.
"""
if isinstance(annotation, TypeVar):
if annotation.__bound__ is None: # when a generic TypeVar has been used.
return default_format_annotation(Any, config)
return default_format_annotation(
annotation.__bound__, config
) # get the annotation for the bound type
return autodoc_custom_types.get(annotation)


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

Expand Down