==================
Sphinx Paramlinks
==================
A `Sphinx <http://sphinx.pocoo.org/>`_ extension which allows ``:param:``
directives within Python documentation to be linkable.
This is an experimental extension that's used by the
`SQLAlchemy <http://www.sqlalchemy.org>`_ project and related projects.
Configuration
=============
Just turn it on in ``conf.py``::
extensions = [
'sphinx_paramlinks',
# your other sphinx extensions
# ...
]
Since version 0.5.3, you can modify how clickable hyperlinks are placed around the names of
the parameter using the ``paramlinks_hyperlink_param`` setting in ``conf.py``::
paramlinks_hyperlink_param='name'
This parameter accepts the following values:
* ``'none'``: No link will be be inserted. The parameter still has a target
attached to it so that you can e.g. jump to it from the search.
* ``'name'``: The parameter name is a clickable hyperlink.
* ``'link_symbol'``: A clickable link symbol is inserted after the parameter
name (but before an eventual type specification). By default, this symbol
only shows when hovering the parameter description (see below)
* ``'name_and_symbol'``: link both the name and also generate a link symbol.
The default is ``paramlinks_hyperlink_param = 'link_symbol'``.
Features
========
* ``:param:`` directives within Sphinx function/method descriptions
will be given a paragraph link so that they can be linked
to externally.
* A new text role ``:paramref:`` is added, which works like ``:meth:``,
``:func:``, etc. Just append the parameter name as an additional token::
:paramref:`.EnvironmentContext.configure.transactional_ddl`
The directive makes use of the existing Python role to do the method/function
lookup, searching first the ``:meth:``, then the ``:class:``, and then the
``:func:`` role; then the parameter name is applied separately to produce the
final reference link. (new in 0.3.4, search for ``:meth:`` / ``:func:`` /
``:class:`` individually rather than using ``:obj:`` which catches lots of
things that don't have parameters)
* The paramlinks are also added to the master index as well as the list
of domain objects, which allows them to be searchable through the
searchindex.js system. (new in 0.3.0)
Stylesheet
==========
The paragraph link involves a short stylesheet, to allow the links to
be visible when hovered. This sheet is called
``sphinx_paramlinks.css`` and the plugin will copy it to the ``_static``
directory of the output automatically. The stylesheet is added to the
``css_files`` list present in the template namespace for Sphinx via the
``Sphinx.add_stylesheet()`` hook.
Customization
-------------
To customize the link styling, you can override the configuration of
``sphinx_paramlinks.css`` by adding a custom style sheet via::
app.add_css_file("path/to/custom.css")
If the parameter name is a hyperlink, the HTML code will look something like
this::
<a class="paramname reference internal" href="#package.method.params.parameter_name">
<strong>parameter_name</strong>
</a>
The class ``paramname`` is defined by ``sphinx-paramlinks`` and can be used to
customize the styling.
If a link symbol is inserted after the hyperlink, the HTML code will look
something like this::
<a class="paramlink headerlink reference internal" href="#package.method.params.parameter_name">ΒΆ</a>
The class ``paramlink`` is defined by ``sphinx-paramlinks`` and can be used to
customize the styling.
Compatibility
=============
Python Compatibility
--------------------
sphinx-paramlinks is fully Python 3 compatible.
Sphinx Compatibility
--------------------
I've tried *very* hard to make as few assumptions as possible about Sphinx
and to use only very simple public APIs, so that architectural changes in future
Sphinx versions won't break this plugin. To come up with this plugin I
spent many hours with Sphinx source and tried many different approaches to
various elements of functionality; hopefully what's here is as simple and
stable as possible based on the current extension capabilities of Sphinx.
One element that involves using a bit of internals is the usage of the
``sphinx.domains.python.PyXRefRole`` class, which is currently the
Sphinx class that defines roles for things like ``:meth:``,
``:func:``, etc. The object is used as-is in order to define the
``:paramref:`` role; the product of this role is later transformed
using standard hooks.
Another assumption is that in order to locate the RST nodes Sphinx
creates for the ``:param:`` tags, we look at ``nodes.strong``,
assuming that this is the type of node currently used to render
``:param:`` within RST. If this changes, or needs to be expanded to
support other domains, this traversal can be opened up as needed.
This part was difficult as Sphinx really doesn't provide any hooks
into how the "Info Field List" aspect of domains is handled.
Overall, the approach here is to apply extra information to constructs
going into the Sphinx system, then do some transformations as the data
comes back out. This relies on as little of how Sphinx does its
thing as possible, rather than going with custom domains and heavy use
of injected APIs which may change in future releases.
Raw data
{
"_id": null,
"home_page": "http://github.com/sqlalchemyorg/sphinx-paramlinks",
"name": "sphinx-paramlinks",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx",
"author": "Mike Bayer",
"author_email": "mike@zzzcomputing.com",
"download_url": "https://files.pythonhosted.org/packages/ae/21/62d3a58ff7bd02bbb9245a63d1f0d2e0455522a11a78951d16088569fca8/sphinx-paramlinks-0.6.0.tar.gz",
"platform": null,
"description": "==================\nSphinx Paramlinks\n==================\n\nA `Sphinx <http://sphinx.pocoo.org/>`_ extension which allows ``:param:``\ndirectives within Python documentation to be linkable.\n\nThis is an experimental extension that's used by the\n`SQLAlchemy <http://www.sqlalchemy.org>`_ project and related projects.\n\nConfiguration\n=============\n\nJust turn it on in ``conf.py``::\n\n extensions = [\n 'sphinx_paramlinks',\n\n # your other sphinx extensions\n # ...\n ]\n\nSince version 0.5.3, you can modify how clickable hyperlinks are placed around the names of\nthe parameter using the ``paramlinks_hyperlink_param`` setting in ``conf.py``::\n\n paramlinks_hyperlink_param='name'\n\nThis parameter accepts the following values:\n\n* ``'none'``: No link will be be inserted. The parameter still has a target\n attached to it so that you can e.g. jump to it from the search.\n\n* ``'name'``: The parameter name is a clickable hyperlink.\n\n* ``'link_symbol'``: A clickable link symbol is inserted after the parameter\n name (but before an eventual type specification). By default, this symbol\n only shows when hovering the parameter description (see below)\n\n* ``'name_and_symbol'``: link both the name and also generate a link symbol.\n\nThe default is ``paramlinks_hyperlink_param = 'link_symbol'``.\n\nFeatures\n========\n\n* ``:param:`` directives within Sphinx function/method descriptions\n will be given a paragraph link so that they can be linked\n to externally.\n\n* A new text role ``:paramref:`` is added, which works like ``:meth:``,\n ``:func:``, etc. Just append the parameter name as an additional token::\n\n :paramref:`.EnvironmentContext.configure.transactional_ddl`\n\n The directive makes use of the existing Python role to do the method/function\n lookup, searching first the ``:meth:``, then the ``:class:``, and then the\n ``:func:`` role; then the parameter name is applied separately to produce the\n final reference link. (new in 0.3.4, search for ``:meth:`` / ``:func:`` /\n ``:class:`` individually rather than using ``:obj:`` which catches lots of\n things that don't have parameters)\n\n* The paramlinks are also added to the master index as well as the list\n of domain objects, which allows them to be searchable through the\n searchindex.js system. (new in 0.3.0)\n\nStylesheet\n==========\n\nThe paragraph link involves a short stylesheet, to allow the links to\nbe visible when hovered. This sheet is called\n``sphinx_paramlinks.css`` and the plugin will copy it to the ``_static``\ndirectory of the output automatically. The stylesheet is added to the\n``css_files`` list present in the template namespace for Sphinx via the\n``Sphinx.add_stylesheet()`` hook.\n\nCustomization\n-------------\n\nTo customize the link styling, you can override the configuration of\n``sphinx_paramlinks.css`` by adding a custom style sheet via::\n\n app.add_css_file(\"path/to/custom.css\")\n\nIf the parameter name is a hyperlink, the HTML code will look something like\nthis::\n\n <a class=\"paramname reference internal\" href=\"#package.method.params.parameter_name\">\n <strong>parameter_name</strong>\n </a>\n\nThe class ``paramname`` is defined by ``sphinx-paramlinks`` and can be used to\ncustomize the styling.\n\nIf a link symbol is inserted after the hyperlink, the HTML code will look\nsomething like this::\n\n <a class=\"paramlink headerlink reference internal\" href=\"#package.method.params.parameter_name\">\u00b6</a>\n\nThe class ``paramlink`` is defined by ``sphinx-paramlinks`` and can be used to\ncustomize the styling.\n\n\nCompatibility\n=============\n\nPython Compatibility\n--------------------\n\nsphinx-paramlinks is fully Python 3 compatible.\n\nSphinx Compatibility\n--------------------\n\nI've tried *very* hard to make as few assumptions as possible about Sphinx\nand to use only very simple public APIs, so that architectural changes in future\nSphinx versions won't break this plugin. To come up with this plugin I\nspent many hours with Sphinx source and tried many different approaches to\nvarious elements of functionality; hopefully what's here is as simple and\nstable as possible based on the current extension capabilities of Sphinx.\n\nOne element that involves using a bit of internals is the usage of the\n``sphinx.domains.python.PyXRefRole`` class, which is currently the\nSphinx class that defines roles for things like ``:meth:``,\n``:func:``, etc. The object is used as-is in order to define the\n``:paramref:`` role; the product of this role is later transformed\nusing standard hooks.\n\nAnother assumption is that in order to locate the RST nodes Sphinx\ncreates for the ``:param:`` tags, we look at ``nodes.strong``,\nassuming that this is the type of node currently used to render\n``:param:`` within RST. If this changes, or needs to be expanded to\nsupport other domains, this traversal can be opened up as needed.\nThis part was difficult as Sphinx really doesn't provide any hooks\ninto how the \"Info Field List\" aspect of domains is handled.\n\nOverall, the approach here is to apply extra information to constructs\ngoing into the Sphinx system, then do some transformations as the data\ncomes back out. This relies on as little of how Sphinx does its\nthing as possible, rather than going with custom domains and heavy use\nof injected APIs which may change in future releases.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Allows param links in Sphinx function/method descriptions to be linkable",
"version": "0.6.0",
"project_urls": {
"Homepage": "http://github.com/sqlalchemyorg/sphinx-paramlinks"
},
"split_keywords": [
"sphinx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae2162d3a58ff7bd02bbb9245a63d1f0d2e0455522a11a78951d16088569fca8",
"md5": "74a1cc657c1ef7015f137bcdf3d30a16",
"sha256": "746a0816860aa3fff5d8d746efcbec4deead421f152687411db1d613d29f915e"
},
"downloads": -1,
"filename": "sphinx-paramlinks-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "74a1cc657c1ef7015f137bcdf3d30a16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12363,
"upload_time": "2023-08-11T16:09:28",
"upload_time_iso_8601": "2023-08-11T16:09:28.604971Z",
"url": "https://files.pythonhosted.org/packages/ae/21/62d3a58ff7bd02bbb9245a63d1f0d2e0455522a11a78951d16088569fca8/sphinx-paramlinks-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-11 16:09:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sqlalchemyorg",
"github_project": "sphinx-paramlinks",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-paramlinks"
}
JSON
