https://github.com/compwa/sphinx-api-relink
Relink type hints in your Sphinx API
Science Score: 26.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
○Academic email domains
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (11.9%) to scientific vocabulary
Repository
Relink type hints in your Sphinx API
Basic Info
Statistics
- Stars: 1
- Watchers: 6
- Forks: 1
- Open Issues: 3
- Releases: 12
Metadata Files
README.md
sphinx-api-relink
This package is a plugin for the sphinx.ext.autodoc extension. The autodoc_type_aliases configuration does not always work well when using postponed evaluation of annotations (PEP 563, i.e. from __future__ import annotations) or when importing through typing.TYPE_CHECKING, because sphinx.ext.autodoc generates the API dynamically (not statically, as opposed to sphinx-autoapi).
Installation
Just install through PyPI with pip:
bash
pip install sphinx-api-relink
Next, in your Sphinx configuration file (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, but it should be an 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 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, 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). 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"]
Owner
- Name: Common Partial Wave Analysis
- Login: ComPWA
- Kind: organization
- Email: compwa@ep1.rub.de
- Location: Germany
- Website: https://compwa.github.io
- Repositories: 36
- Profile: https://github.com/ComPWA
Making amplitude analysis reproducible, understandable, and easy to do
GitHub Events
Total
- Release event: 1
- Delete event: 5
- Push event: 18
- Pull request review event: 3
- Pull request event: 8
- Create event: 5
Last Year
- Release event: 1
- Delete event: 5
- Push event: 18
- Pull request review event: 3
- Pull request event: 8
- Create event: 5
Issues and Pull Requests
Last synced: 10 months ago
All Time
- Total issues: 5
- Total pull requests: 32
- Average time to close issues: 24 days
- Average time to close pull requests: 3 days
- Total issue authors: 1
- Total pull request authors: 3
- Average comments per issue: 0.4
- Average comments per pull request: 0.0
- Merged pull requests: 30
- Bot issues: 0
- Bot pull requests: 7
Past Year
- Issues: 2
- Pull requests: 12
- Average time to close issues: 7 days
- Average time to close pull requests: 3 days
- Issue authors: 1
- Pull request authors: 3
- Average comments per issue: 0.0
- Average comments per pull request: 0.0
- Merged pull requests: 10
- Bot issues: 0
- Bot pull requests: 4
Top Authors
Issue Authors
- redeboer (6)
Pull Request Authors
- redeboer (29)
- pre-commit-ci[bot] (10)
- grayson-helmholz (2)
Top Labels
Issue Labels
Pull Request Labels
Dependencies
- ComPWA/actions/clean-caches v1 composite
- JulienKode/pull-request-name-linter-action v0.5.0 composite
- actions/checkout v4 composite
- docker://agilepathway/pull-request-label-checker latest composite
- release-drafter/release-drafter v5 composite
- Sphinx >=4.4
- docutils *
- pip
- python 3.9.*