# `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)
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.7",
"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/b9/a2/2a88ff22f4ea8a3fd9bcb4200f1bf9ff558276e915b7c9beaf25bb8053bf/sphinx_api_relink-0.0.9.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\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.9",
"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": "150a8c4dba0094c349211adc8c9161803547fbedd7c3b1f9123c544aa3da7cb8",
"md5": "e7b324d1d16083fb1b6a8d74a27e170f",
"sha256": "d9395433391445aeb08a5608f82923d78f859ecc257ed91f2d0f5fcfe08d59e4"
},
"downloads": -1,
"filename": "sphinx_api_relink-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7b324d1d16083fb1b6a8d74a27e170f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12029,
"upload_time": "2024-04-23T12:53:32",
"upload_time_iso_8601": "2024-04-23T12:53:32.157775Z",
"url": "https://files.pythonhosted.org/packages/15/0a/8c4dba0094c349211adc8c9161803547fbedd7c3b1f9123c544aa3da7cb8/sphinx_api_relink-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9a22a88ff22f4ea8a3fd9bcb4200f1bf9ff558276e915b7c9beaf25bb8053bf",
"md5": "e02053c57527b3cdd2bca28ef2b8a9dc",
"sha256": "f438a04714c9d54e084d2efc72d7f57af785705a6d6793bce61b3c50a26456c7"
},
"downloads": -1,
"filename": "sphinx_api_relink-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "e02053c57527b3cdd2bca28ef2b8a9dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18027,
"upload_time": "2024-04-23T12:53:33",
"upload_time_iso_8601": "2024-04-23T12:53:33.827124Z",
"url": "https://files.pythonhosted.org/packages/b9/a2/2a88ff22f4ea8a3fd9bcb4200f1bf9ff558276e915b7c9beaf25bb8053bf/sphinx_api_relink-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 12:53:33",
"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
