sphinx-contrib / httpdomain

Documenting RESTful HTTP APIs

Home Page:https://pypi.org/project/sphinxcontrib-httpdomain/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Unable to use role to reference a resource that has :noindex:

jessetan opened this issue · comments

If a resource is documented as:

.. http:get:: /myresource

  This is a resource.

It can be referenced by :http:get:`/myresource` , which turns into a clickable link.

However, I do not want my PDF to contain a routing table. So I add :noindex to the directive.
Now the role no longer produces a clickable link and Sphinx logs a warning WARNING: Cannot resolve reference to <#text: 'GET /myresource'>.

Is there a way to make a resource not appear in the routing table in a way that the role can still link to the directive?

As a workaround, I'm using a very small extension:

from sphinxcontrib.httpdomain import HTTPIndex

def _generate(self, docnames=None):
    return ([], True)

def setup(app):
    # Override routing table generation
    HTTPIndex.generate = _generate

    return {'version': '0.1'}   # identifies the version of our extension

I added the code to conf.py, referring to jessetan's workaround. It works well for me.

from sphinxcontrib.httpdomain import HTTPIndex
HTTPIndex.generate = lambda a, b = None: ([], True)