Skip to content
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

Can't use intersphinx with Sphinx's documentation settings #5562

Open
ericholscher opened this issue Oct 24, 2018 · 2 comments
Open

Can't use intersphinx with Sphinx's documentation settings #5562

ericholscher opened this issue Oct 24, 2018 · 2 comments

Comments

@ericholscher
Copy link
Contributor

ericholscher commented Oct 24, 2018

Problem

  • I can't use intersphinx with Sphinx's documentation settings

Procedure to reproduce the problem

intersphinx_mapping = {
    'sphinx': ('http://sphinx.readthedocs.io/en/latest/', None),
}
:ref:`gettext_uuid <sphinx:gettext_uuid>`

Error logs / results

/Users/eric/projects/readthedocs.org/docs/guides/manage-translations.rst:43: WARNING: undefined label: sphinx:gettext_uuid (if the link has no caption the label must precede a section header)

Expected results

It should generate a URL to the proper Sphinx docs

Debugging

I tracked this down to the fact that my Sphinx run doesn't know about the std:confval reference type. I have it in the intersphinx data:

ipdb> env.intersphinx_inventory.keys()
dict_keys(['py:class', 'py:method', 'py:module', 'py:attribute', 'py:data', 'py:function', 'py:classmethod', 'py:exception', 'py:staticmethod', 'std:option', 'std:label', 'std:setting', 'std:envvar', 'std:templatefilter', 'std:term', 'std:fieldlookup', 'std:templatetag', 'std:django-admin', 'std:doc', 'c:var', 'c:type', 'c:function', 'c:member', 'c:macro', 'std:pdbcommand', 'std:cmdoption', 'std:opcode', 'std:token', 'std:2to3fixer', 'cpp:class', 'cpp:union', 'cpp:member', 'cpp:type', 'cpp:templateParam', 'cpp:function', 'cpp:functionParam', 'cpp:concept', 'js:function', 'js:class', 'rst:role', 'rst:directive', 'std:confval', 'std:event'])

But when I create the list of possible targets from my list of domains, it isn't there:

ipdb> objtypes
['c:function', 'c:member', 'c:macro', 'c:type', 'c:var', 'cpp:class', 'cpp:union', 'cpp:function', 'cpp:member', 'cpp:type', 'cpp:concept', 'cpp:enum', 'cpp:enumerator', 'js:function', 'js:method', 'js:class', 'js:data', 'js:attribute', 'js:module', 'py:function', 'py:data', 'py:class', 'py:exception', 'py:method', 'py:classmethod', 'py:staticmethod', 'py:attribute', 'py:module', 'rst:directive', 'rst:role', 'std:term', 'std:token', 'std:label', 'std:envvar', 'std:cmdoption', 'std:doc', 'std:setting', 'http:options', 'http:head', 'http:post', 'http:get', 'http:put', 'http:patch', 'http:delete', 'http:trace', 'http:connect', 'http:copy', 'http:any']

Code

I believe the issue is the logic here, which takes into account the installed Domains, but not the known labels in the intersphinx_inventory:

objtypes = ['%s:%s' % (domain.name, objtype)
for domain in env.domains.values()
for objtype in domain.object_types]

@tk0miya
Copy link
Member

tk0miya commented Oct 30, 2018

It is custom object type defined in our doc:

sphinx/doc/conf.py

Lines 140 to 142 in a4cce3e

app.add_object_type('confval', 'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')

You can refer it if you'll also define it on your project.

@AA-Turner AA-Turner added this to the some future version milestone Sep 29, 2022
jnikula added a commit to jnikula/hawkmoth that referenced this issue Jan 20, 2023
First, fix the intersphinx URL

Second, add 'confval' object type [1] to be able to reference objects of
that type using intersphinx. (Yes, it's also possible to turn conf.py
into an extension just by adding a setup() function.)

Third, fix the intersphinx references [2].

[1] sphinx-doc/sphinx#5562 (comment)
[2] https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
jnikula added a commit to jnikula/hawkmoth that referenced this issue Jan 21, 2023
The object type for the "extensions" target has changed to
"confval". It's a custom object type in the Sphinx documentation, and
intersphinx is unable to reference it unless we define that locally as
well. [1]

Turn conf.py into an extension by adding the setup() function (yes,
that's indeed possible), add the "confval" object type, and fix the
extensions reference role to match that.

[1] sphinx-doc/sphinx#5562 (comment)
jnikula added a commit to jnikula/hawkmoth that referenced this issue Jan 22, 2023
The object type for the "extensions" target has changed to
"confval". It's a custom object type in the Sphinx documentation, and
intersphinx is unable to reference it unless we define that locally as
well. [1]

Turn conf.py into an extension by adding the setup() function (yes,
that's indeed possible), add the "confval" object type, and fix the
extensions reference role to match that.

[1] sphinx-doc/sphinx#5562 (comment)
@webknjaz
Copy link
Contributor

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

No branches or pull requests

4 participants