# `sphinx-api-relink`
[](https://pypi.org/project/sphinx-api-relink)
[](https://pypi.org/project/sphinx-api-relink)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://open.vscode.dev/ComPWA/sphinx-api-relink)
[](https://github.com/ComPWA/sphinx-api-relink/actions?query=branch%3Amain+workflow%3ACI)
[](https://mypy.readthedocs.io)
[](https://results.pre-commit.ci/latest/github/ComPWA/sphinx-api-relink/main)
[](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
[](https://github.com/prettier/prettier)
[](https://github.com/astral-sh/ruff)
[](https://github.com/astral-sh/uv)
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"]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-api-relink",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "compwa-admin@ep1.rub.de",
"keywords": "autodoc, reference, relink, sphinx",
"author": null,
"author_email": "Common Partial Wave Analysis <compwa-admin@ep1.rub.de>",
"download_url": "https://files.pythonhosted.org/packages/e3/e2/60ddb1b9fd51438d191e06048e82bb97101f00620c9cd7ab5b792e190494/sphinx_api_relink-0.0.12.tar.gz",
"platform": null,
"description": "# `sphinx-api-relink`\n\n[](https://pypi.org/project/sphinx-api-relink)\n[](https://pypi.org/project/sphinx-api-relink)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://open.vscode.dev/ComPWA/sphinx-api-relink)\n[](https://github.com/ComPWA/sphinx-api-relink/actions?query=branch%3Amain+workflow%3ACI)\n[](https://mypy.readthedocs.io)\n[](https://results.pre-commit.ci/latest/github/ComPWA/sphinx-api-relink/main)\n[](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)\n[](https://github.com/prettier/prettier)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/astral-sh/uv)\n\nThis 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)).\n\n## Installation\n\nJust install through [PyPI](https://pypi.org) with `pip`:\n\n```bash\npip install sphinx-api-relink\n```\n\nNext, in your [Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) (`conf.py`), add `\"sphinx_api_relink\"` to your `extensions`:\n\n```python\nextensions = [\n \"sphinx_api_relink\",\n]\n```\n\n## Usage\n\nThere 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:\n\n```python\napi_target_substitutions: dict[str, str | tuple[str, str]] = {\n \"sp.Expr\": \"sympy.core.expr.Expr\",\n \"Protocol\": (\"obj\", \"typing.Protocol\"),\n}\n```\n\nThe 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):\n\n```python\napi_target_types: dict[str, str] = {\n \"RangeDefinition\": \"obj\",\n}\n```\n\nThe 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:\n\n```\napi_github_repo: str = \"ComPWA/sphinx-api-relink\"\n```\n\nSet `api_linkcode_debug = True` to print the generated URLs to the console.\n\n## Generate API\n\nTo generate the API for [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html), add this to your `conf.py`:\n\n```python\ngenerate_apidoc_package_path = \"../src/my_package\" # relative to conf.py\n```\n\nMultiple packages can be listed as well:\n\n```python\ngenerate_apidoc_package_path = [\n \"../src/package1\",\n \"../src/package2\",\n]\n```\n\nThe 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:\n\n```python\ngenerate_apidoc_use_compwa_template = False\n```\n\nOther configuration values (with their defaults):\n\n```python\ngenerate_apidoc_directory = \"api\"\ngenerate_apidoc_excludes = [\"version.py\"]\n```\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Relink type hints in your Sphinx API",
"version": "0.0.12",
"project_urls": {
"Changelog": "https://github.com/ComPWA/sphinx-api-relink/releases",
"Documentation": "https://github.com/ComPWA/sphinx-api-relink/blob/main/README.md",
"Source": "https://github.com/ComPWA/sphinx-api-relink",
"Tracker": "https://github.com/ComPWA/sphinx-api-relink/issues"
},
"split_keywords": [
"autodoc",
" reference",
" relink",
" sphinx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5e32852dd608bb9b68cc2d1975e7fa1029e73a360d3b102c073edacc405a5a2",
"md5": "f6fa8dcfc378a236dd7f134ab187c13e",
"sha256": "974aca39db9937e5d3bcab189d9e43d55e299a103dc734f8a963f8a76840735c"
},
"downloads": -1,
"filename": "sphinx_api_relink-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6fa8dcfc378a236dd7f134ab187c13e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11865,
"upload_time": "2024-10-29T10:50:48",
"upload_time_iso_8601": "2024-10-29T10:50:48.677850Z",
"url": "https://files.pythonhosted.org/packages/f5/e3/2852dd608bb9b68cc2d1975e7fa1029e73a360d3b102c073edacc405a5a2/sphinx_api_relink-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3e260ddb1b9fd51438d191e06048e82bb97101f00620c9cd7ab5b792e190494",
"md5": "6bbc180029cfb3a5b880ad59711992ed",
"sha256": "b995a6482e6bebc9aafd3194374acac2beff761f62ea2da87da35c53897b4410"
},
"downloads": -1,
"filename": "sphinx_api_relink-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "6bbc180029cfb3a5b880ad59711992ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18321,
"upload_time": "2024-10-29T10:50:49",
"upload_time_iso_8601": "2024-10-29T10:50:49.890461Z",
"url": "https://files.pythonhosted.org/packages/e3/e2/60ddb1b9fd51438d191e06048e82bb97101f00620c9cd7ab5b792e190494/sphinx_api_relink-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 10:50:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ComPWA",
"github_project": "sphinx-api-relink",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-api-relink"
}
JSON
