"interface" role and object type is not implemented properly

[a3kov]

Looks like it could be a bug in this package - correct me if I'm wrong.
This one fails:

:interface:`pyramid.interfaces.ISession`

This one fails also:

:class:`pyramid.interfaces.ISession`

Any ideas ?

[tseaver]

Hmm, the Pyramid docs themselves show that it works. e.g.:

class IContextFound(Interface):
    """ An event type that is emitted after :app:`Pyramid` finds a
    :term:`context` object but before it calls any view code.  See the
    documentation attached to :class:`pyramid.events.ContextFound`
    for more information.
    .. note::

      For backwards compatibility with versions of
       :app:`Pyramid` before 1.0, this event interface can also be
       imported as :class:`pyramid.interfaces.IAfterTraversal`.
    """

which renders as expected.

What are you expecting to see that isn't there?

[a3kov]

Well local references could be different as intersphinx is not involved probably.
I am expecting to see a hyperlink - last time I checked :interface: role got Sphinx complaining and
:class: role was rendered as bold text instead of a link.

[a3kov]

I tried to copy some interface to my code, and locally it doesn't work also.
Unknown interpreted text role "interface"
In conf.py I have:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'repoze.sphinx.autointerface',
]

The module is installed, but looks like doesn't work for some reason.

[a3kov]

Local copy works, but not fully - :interface: role doesn't work still. The following works:

1. .. autointerface:: localinterface
2. :class:`localinterface`

The end result: 2 is a link pointing to 1

[a3kov]

If you run the following:

python -m sphinx.ext.intersphinx 'http://docs.pylonsproject.org/projects/pyramid/en/latest/objects.inv'

you will notice that interfaces are exported as py:interface role, and not as a py:class role. But it looks like the interface role is not implemented fully.

[a3kov]

So there are 2 issues here actually:

• :class: role not externally reference-able (if it was intended, but it looks like it was, since the Pyramid itself uses this type of references in it's own docs)
• :interface: role not implemented fully

[a3kov]

Sphinx API is a total mess. Why is there add_role_to_domain(), and add_directive_to_domain() but no add_object_type_to_domain() ? Apparently the resolution does not work without a proper object type, and the current code had to add it to a new domain and to recreate the domain - feels like a hack, but now I understand the reason - looks like there's no other "proper" way to do it

[a3kov]

I've fixed this...will create pull request a bit later, need to sleep now ;)

[jamadden]

On RTD, which is apparently using Sphinx 1.5.3 I'm not having any trouble using intersphinx references to interfaces. E.g., this class in zope.app.apidoc references IReadContainer from zope.container and the link is followed.

You can see the source uses the :class: domain:

@implementer(ILocation)
class APIDocumentation(ReadContainerBase):
    """
    The collection of all API documentation.

    This documentation is implemented using a simply
    :class:`~zope.container.interfaces.IReadContainer`. The items of
    the container are all registered utilities for
    :class:`~zope.app.apidoc.interfaces.IDocumentationModule`.
    """

The only (minor) problem I'm having there is that the fuzzy-matching doesn't work for intersphinx references. That is, using :class:~.IReadContainer doesn't find the reference. But that's a known issue.

However, locally, where I'm using sphinx 1.6.1, the link doesn't work. If I downgrade to Sphinx 1.5.6, the link works.

So this is an issue introduced with Sphinx 1.6.