Python Project *sphinx-pytype-substitution*
-------------------------------------------
|codeship|_ |readthedocs|_ |license|_ |github_version|_ |pip_version|_
|py_version|_ |pypi_downloads|_
.. |codeship| image:: https://img.shields.io/codeship/452428/master.svg
.. _codeship: https://codeship.com//projects/452428
.. |readthedocs| image:: https://img.shields.io/readthedocs/sphinx-pytype-substitution
.. _readthedocs: https://sphinx-pytype-substitution.readthedocs.io/en/latest/intro.html
.. |license| image:: https://img.shields.io/github/license/sonntagsgesicht/sphinx-pytype-substitution
.. _license: https://github.com/sonntagsgesicht/sphinx-pytype-substitution/raw/master/LICENSE
.. |github_version| image:: https://img.shields.io/github/release/sonntagsgesicht/sphinx-pytype-substitution?label=github
.. _github_version: https://github.com/sonntagsgesicht/sphinx-pytype-substitution/releases
.. |pip_version| image:: https://img.shields.io/pypi/v/sphinx-pytype-substitution
.. _pip_version: https://pypi.org/project/sphinx-pytype-substitution/
.. |py_version| image:: https://img.shields.io/pypi/pyversions/sphinx-pytype-substitution
.. _py_version: https://pypi.org/project/sphinx-pytype-substitution/
.. |pypi_frequency| image:: https://img.shields.io/pypi/dm/sphinx-pytype-substitution
.. _pypi_frequency: https://pypi.org/project/sphinx-pytype-substitution/
.. |pypi_downloads| image:: https://pepy.tech/badge/sphinx-pytype-substitution
.. _pypi_downloads: https://pypi.org/project/sphinx-pytype-substitution/
Introduction
------------
:code:`sphinx-pytype-substitution` generates
`restructuredtext substitutions <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references>`_
for
`python cross references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-roles>`_.
Once added to the
`extensions list <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions>`_
of the
`Sphinx <https://www.sphinx-doc.org>`_
`configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#module-conf>`_
file :code:`conf.py`
it adds short and handy substitutions for
`modules <https://docs.python.org/3/tutorial/modules.html#modules>`_
and
`classes <https://docs.python.org/3/reference/compound_stmts.html#class-definitions>`_.
So, on one side it becomes easy to add cross references to some
api documentation in the project. And on the other side these references
are still easy readable, even if the text is displayed directly
(as it happens on `GitHub.com <https://github.com/sonntagsgesicht/sphinx_pytype_substitution>`_
or on `PyPi.org <https://pypi.org/project/sphinx-pytype-substitution/>`_).
Install
-------
The latest stable version can always be installed or updated via pip:
.. code-block:: bash
$ pip install sphinx-pytype-substitution
Usage
-----
Once available add the extension to then extensions list in :code:`config.py`
.. code-block:: python
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_pytype_substitution',
'sphinx_rtd_theme',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon'
]
And add the modules or classes to reference to as
.. code-block:: python
# -- Config for pytype_substitution extension ------------------------------
pytype_substitutions = pkg, # package, module or class to reference to
Additional options let select specific references
.. code-block:: python
pytype_match_pattern = '' # regex to filter entities to ref to
pytype_exclude_pattern = '' # regex to exclude entities to ref to
and decide if the substitution should have *short* or *full* format, i.e.
.. code-block:: python
pytype_short_ref = True # drop module from reference (if it does not conflict)
for :code:`|date()|` rather than :code:`|datetime.date()|`.
Note, sometimes the defining module matters as for :code:`|open()|` vs
:code:`|gzip.open()|`.
During initialisation process of Sphinx the list of substitutions is generated
and added to
`rst_epilog <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog>`_.
So the substitutions are available for every page.
To see which substitutions are added add
.. code-block:: python
pytype_show = True # print out all pytype_substitutions
License
-------
Code and documentation are available according to the license (see LICENSE file in repository).
Raw data
{
"_id": null,
"home_page": "https://github.com/sonntagsgesicht/sphinx-pytype-substitution",
"name": "sphinx-pytype-substitution",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "sonntagsgesicht",
"author_email": "sonntagsgesicht@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/eb/5d/feab982f5dce36abaa9a9c8a0aaefc3da1dc2cc44cbf0bdef2ad226cb46d/sphinx_pytype_substitution-0.1.2.zip",
"platform": "any",
"description": "\n\nPython Project *sphinx-pytype-substitution*\n-------------------------------------------\n\n|codeship|_ |readthedocs|_ |license|_ |github_version|_ |pip_version|_\n|py_version|_ |pypi_downloads|_\n\n\n.. |codeship| image:: https://img.shields.io/codeship/452428/master.svg\n.. _codeship: https://codeship.com//projects/452428\n\n.. |readthedocs| image:: https://img.shields.io/readthedocs/sphinx-pytype-substitution\n.. _readthedocs: https://sphinx-pytype-substitution.readthedocs.io/en/latest/intro.html\n\n.. |license| image:: https://img.shields.io/github/license/sonntagsgesicht/sphinx-pytype-substitution\n.. _license: https://github.com/sonntagsgesicht/sphinx-pytype-substitution/raw/master/LICENSE\n\n.. |github_version| image:: https://img.shields.io/github/release/sonntagsgesicht/sphinx-pytype-substitution?label=github\n.. _github_version: https://github.com/sonntagsgesicht/sphinx-pytype-substitution/releases\n\n.. |pip_version| image:: https://img.shields.io/pypi/v/sphinx-pytype-substitution\n.. _pip_version: https://pypi.org/project/sphinx-pytype-substitution/\n\n.. |py_version| image:: https://img.shields.io/pypi/pyversions/sphinx-pytype-substitution\n.. _py_version: https://pypi.org/project/sphinx-pytype-substitution/\n\n.. |pypi_frequency| image:: https://img.shields.io/pypi/dm/sphinx-pytype-substitution\n.. _pypi_frequency: https://pypi.org/project/sphinx-pytype-substitution/\n\n.. |pypi_downloads| image:: https://pepy.tech/badge/sphinx-pytype-substitution\n.. _pypi_downloads: https://pypi.org/project/sphinx-pytype-substitution/\n\n\nIntroduction\n------------\n\n:code:`sphinx-pytype-substitution` generates\n`restructuredtext substitutions <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references>`_\nfor\n`python cross references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-roles>`_.\n\nOnce added to the\n`extensions list <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions>`_\nof the\n`Sphinx <https://www.sphinx-doc.org>`_\n`configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#module-conf>`_\nfile :code:`conf.py`\nit adds short and handy substitutions for\n`modules <https://docs.python.org/3/tutorial/modules.html#modules>`_\nand\n`classes <https://docs.python.org/3/reference/compound_stmts.html#class-definitions>`_.\n\nSo, on one side it becomes easy to add cross references to some\napi documentation in the project. And on the other side these references\nare still easy readable, even if the text is displayed directly\n(as it happens on `GitHub.com <https://github.com/sonntagsgesicht/sphinx_pytype_substitution>`_\nor on `PyPi.org <https://pypi.org/project/sphinx-pytype-substitution/>`_).\n\n\nInstall\n-------\n\nThe latest stable version can always be installed or updated via pip:\n\n.. code-block:: bash\n\n $ pip install sphinx-pytype-substitution\n\n\nUsage\n-----\n\nOnce available add the extension to then extensions list in :code:`config.py`\n\n.. code-block:: python\n\n # Add any Sphinx extension module names here, as strings. They can be\n # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n # ones.\n extensions = [\n 'sphinx_pytype_substitution',\n 'sphinx_rtd_theme',\n 'sphinx.ext.autodoc',\n 'sphinx.ext.autosummary',\n 'sphinx.ext.doctest',\n 'sphinx.ext.mathjax',\n 'sphinx.ext.viewcode',\n 'sphinx.ext.napoleon'\n ]\n\nAnd add the modules or classes to reference to as\n\n.. code-block:: python\n\n # -- Config for pytype_substitution extension ------------------------------\n\n pytype_substitutions = pkg, # package, module or class to reference to\n\n\nAdditional options let select specific references\n\n.. code-block:: python\n\n pytype_match_pattern = '' # regex to filter entities to ref to\n pytype_exclude_pattern = '' # regex to exclude entities to ref to\n\nand decide if the substitution should have *short* or *full* format, i.e.\n\n.. code-block:: python\n\n pytype_short_ref = True # drop module from reference (if it does not conflict)\n\nfor :code:`|date()|` rather than :code:`|datetime.date()|`.\nNote, sometimes the defining module matters as for :code:`|open()|` vs\n:code:`|gzip.open()|`.\n\nDuring initialisation process of Sphinx the list of substitutions is generated\nand added to\n`rst_epilog <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog>`_.\n\nSo the substitutions are available for every page.\n\n\nTo see which substitutions are added add\n\n.. code-block:: python\n\n pytype_show = True # print out all pytype_substitutions\n\n\nLicense\n-------\n\nCode and documentation are available according to the license (see LICENSE file in repository).\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "auto substitution for python types like modules, classes and functions (created by auxilium)",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/sonntagsgesicht/sphinx-pytype-substitution"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb5dfeab982f5dce36abaa9a9c8a0aaefc3da1dc2cc44cbf0bdef2ad226cb46d",
"md5": "6a1e409801e8d0c718b703399b18c48a",
"sha256": "1f52113205545d191fed0f91e445411609f15d2a1cad20bb74aa4aff8e1a2711"
},
"downloads": -1,
"filename": "sphinx_pytype_substitution-0.1.2.zip",
"has_sig": false,
"md5_digest": "6a1e409801e8d0c718b703399b18c48a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18321,
"upload_time": "2021-12-18T16:46:35",
"upload_time_iso_8601": "2021-12-18T16:46:35.673678Z",
"url": "https://files.pythonhosted.org/packages/eb/5d/feab982f5dce36abaa9a9c8a0aaefc3da1dc2cc44cbf0bdef2ad226cb46d/sphinx_pytype_substitution-0.1.2.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-12-18 16:46:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sonntagsgesicht",
"github_project": "sphinx-pytype-substitution",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "auxilium",
"specs": []
},
{
"name": "sphinx-nameko-theme",
"specs": []
}
],
"lcname": "sphinx-pytype-substitution"
}
JSON
