Metadata-Version: 2.1
Name: sphinx-api-relink
Version: 0.0.9
Summary: Relink type hints in your Sphinx API
Author-email: Common Partial Wave Analysis <compwa-admin@ep1.rub.de>
Maintainer-email: compwa-admin@ep1.rub.de
License: BSD 3-Clause License
Project-URL: Changelog, https://github.com/ComPWA/sphinx-api-relink/releases
Project-URL: Documentation, https://github.com/ComPWA/sphinx-api-relink/blob/main/README.md
Project-URL: Source, https://github.com/ComPWA/sphinx-api-relink
Project-URL: Tracker, https://github.com/ComPWA/sphinx-api-relink/issues
Keywords: autodoc,reference,relink,sphinx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx>=4.4
Requires-Dist: colorama
Requires-Dist: docutils
Requires-Dist: importlib-metadata; python_version < "3.8.0"
Requires-Dist: typing-extensions; python_version < "3.8.0"
Provides-Extra: dev
Requires-Dist: sphinx-api-relink[sty]; extra == "dev"
Provides-Extra: sty
Requires-Dist: mypy; extra == "sty"
Requires-Dist: pre-commit>=1.4.0; extra == "sty"
Requires-Dist: ruff; extra == "sty"
Requires-Dist: sphinx-api-relink[types]; extra == "sty"
Provides-Extra: types
Requires-Dist: types-colorama; extra == "types"
Requires-Dist: types-docutils; extra == "types"
Requires-Dist: types-requests; extra == "types"

# `sphinx-api-relink`

[![PyPI package](https://badge.fury.io/py/sphinx-api-relink.svg)](https://pypi.org/project/sphinx-api-relink)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-api-relink)](https://pypi.org/project/sphinx-api-relink)
[![BSD 3-Clause license](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-api-relink)
[![CI status](https://github.com/ComPWA/sphinx-api-relink/workflows/CI/badge.svg)](https://github.com/ComPWA/sphinx-api-relink/actions?query=branch%3Amain+workflow%3ACI)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy.readthedocs.io)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/ComPWA/sphinx-api-relink/main.svg)](https://results.pre-commit.ci/latest/github/ComPWA/sphinx-api-relink/main)
[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

This package is a plugin for the [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extension. The [`autodoc_type_aliases`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases) configuration does not always work well when using postponed evaluation of annotations ([PEP 563](https://peps.python.org/pep-0563), i.e. `from __future__ import annotations`) or when importing through [`typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING), because `sphinx.ext.autodoc` generates the API dynamically (not statically, as opposed to [`sphinx-autoapi`](https://github.com/readthedocs/sphinx-autoapi)).

## Installation

Just install through [PyPI](https://pypi.org) with `pip`:

```bash
pip install sphinx-api-relink
```

Next, in your [Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) (`conf.py`), add `"sphinx_api_relink"` to your `extensions`:

```python
extensions = [
    "sphinx_api_relink",
]
```

## Usage

There are two ways to relink type hint references in your API. The first one, **`api_target_substitutions`**, should be used when the target is different than the type hint itself:

```python
api_target_substitutions: dict[str, str | tuple[str, str]] = {
    "sp.Expr": "sympy.core.expr.Expr",
    "Protocol": ("obj", "typing.Protocol"),
}
```

The second, **`api_target_types`**, is useful when you want to redirect the reference **type**. This is for instance useful when Sphinx thinks the reference is a [`class`](https://www.sphinx-doc.org/en/master/usage/domains/python.html#role-py-class), but it should be an [`obj`](https://www.sphinx-doc.org/en/master/usage/domains/python.html#role-py-obj):

```python
api_target_types: dict[str, str] = {
    "RangeDefinition": "obj",
}
```

The extension can also link to the source code on GitHub through the [`sphinx.ext.linkcode`](https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html) extension. To activate, specify the GitHub organization and the repository name as follows:

```
api_github_repo: str = "ComPWA/sphinx-api-relink"
```

Set `api_linkcode_debug = True` to print the generated URLs to the console.

## Generate API

To generate the API for [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html), add this to your `conf.py`:

```python
generate_apidoc_package_path = "../src/my_package"  # relative to conf.py
```

Multiple packages can be listed as well:

```python
generate_apidoc_package_path = [
    "../src/package1",
    "../src/package2",
]
```

The API is generated with the same style used by the ComPWA repositories (see e.g. [ampform.rtfd.io/en/stable/api/ampform.html](https://ampform.readthedocs.io/en/stable/api/ampform.html)). To use the default template, set:

```python
generate_apidoc_use_compwa_template = False
```

Other configuration values (with their defaults):

```python
generate_apidoc_directory = "api"
generate_apidoc_excludes = ["version.py"]
```
