search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.56k stars 2.12k forks source link

Interest in integrating the sphinx-paramlinks extension #11456

Open CaselIT opened 1 year ago

CaselIT commented 1 year ago

Hello

I've opened this issue to ask if there is interest in integrating the features of the https://github.com/sqlalchemyorg/sphinx-paramlinks extension.

The main feature of this extension are, like mentioned in its readme, to allow link to function and method params and cross-link to them.

A live example is in the sqlalchemy does. For example this is a link to a function param, and in the parameter description there is a cross-link the another function parameter (create_engine.echo). The python source for that part is this https://github.com/sqlalchemy/sqlalchemy/blob/5f26a66aeca841ca2ec714d3473394d61a29ed9a/lib/sqlalchemy/engine/base.py#L302-L310

I've never contributed to sphinx, but if there is interest in this feature I can work to create an PR to upstream it. I've asked the creator of the extension, @zzzeek, and he's ok with it.

picnixz commented 1 year ago

I am in favor of this addition, but the decision is left to the maintainers @AA-Turner (and maybe @tk0miya).

An alternative worth to consider is incorporating this mechanism directly at the role level instead (when parsing :param:) and having a simple boolean enabling the creation of a reference node.

electric-coder commented 1 year ago

As a user, I think this is a highly desirable feature since there's no way to write cross-references to parameters using only sphinx.ext and Sphinx core. (I don't have a workaround and my alternative has been to mention parameters in prose with double backticks to at least get them highlighted.)

The only reason I haven't adopted sphinx.paramlinks is to avoid adding another 3rd party dependency to my projects.

The only problem is, afaict, that the Sphinx project itself doesn't seem to currently have enough volunteers to keep up with the growing backlog of maintenance issues. (And it remains to be seen if Sphinx will be able to continue supporting major changes to the typing module...)

electric-coder commented 1 year ago

Related, one of the oldest open Sphinx issues: #538.

CaselIT commented 1 year ago

Did not know about that issue. I'll post a link to this issue there