Skip to content

Parameter types in the JavaScript domain have erroneous brackets #13217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AA-Turner opened this issue Jan 7, 2025 Discussed in #13216 · 3 comments · May be fixed by #13569
Open

Parameter types in the JavaScript domain have erroneous brackets #13217

AA-Turner opened this issue Jan 7, 2025 Discussed in #13216 · 3 comments · May be fixed by #13569

Comments

@AA-Turner
Copy link
Member

AA-Turner commented Jan 7, 2025

Reported in https://github.com/orgs/sphinx-doc/discussions/13216 by @resnickj

Originally posted by resnickj January 7, 2025
This can be seen right on the Sphinx documentation page for the JavaScript domain: https://www.sphinx-doc.org/en/master/usage/domains/javascript.html

image

I'm working on a particular set of docs which were last built with Sphinx 3.5, and it did not output parentheses after parameter types. Was this change made intentionally? (I'm not sure why it would ever make sense to have parentheses after parameter type names.) Is there a way to revert to the old behaviour?

Thanks!

@AA-Turner AA-Turner changed the title Why do parameter types in the JavaScript domain have parentheses appended? Parameter types in the JavaScript domain have erroneous brackets Jan 7, 2025
@AA-Turner AA-Turner added this to the 8.2.0 milestone Feb 10, 2025
@picnixz
Copy link
Member

picnixz commented Feb 11, 2025

I think it's because we specify 'class': JSXRefRole(fix_parens=True) instead of fix_parens=False (which is what the Python domain does). Since the types are rendered as if they were class references, they get an additional () suffix). I need to check this but I guess that's one reason.

EDIT: ok it's not that. But looking at the HTML we have:

<code class="xref js js-func docutils literal notranslate"><span class="pre">string()</span></code>

so string is treated as a js-func. I'll investigate more.

EDIT 2: Found a fix.

@picnixz
Copy link
Member

picnixz commented Feb 11, 2025

The issue is with JSCallable:

    doc_field_types = [
        TypedField(
            'arguments',
            label=_('Arguments'),
            names=('argument', 'arg', 'parameter', 'param'),
            typerolename='func',
            typenames=('paramtype', 'type'),
        ),
        GroupedField(
            'errors',
            label=_('Throws'),
            rolename='func',
            names=('throws',),
            can_collapse=True,
        ),
   ...

The role is func instead of class. But changing it into class leads to lots of not-found references. Could be fine to change it but this could annoy existing builds, so we could first suppress the reference errors arising from those places (it surprises me though that the func role didn't actually lead to ref errors as well).

@AA-Turner AA-Turner modified the milestones: 8.2.0, 8.x Feb 16, 2025
@AA-Turner AA-Turner modified the milestones: 8.x, 8.3.0 Feb 23, 2025
@SilverRainZ
Copy link
Contributor

@picnixz The missing reference warning about js:func is silenced by the custom nitpick_ignore in doc/conf.py.

So I think changing the rolename from func to class will not annoy existing builds, how about just changing it and fixing the fix_parens? I am happy to file a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants