Substitutions inside links in reST / Sphinx

Question

I am using Sphinx to document a webservice that will be deployed in different servers. The documentation is full of URL examples for the user to click and they should just work. My problem is that the host, port and deployment root will vary and the documentation will have to be re-generated for every deployment.

I tried defining substitutions like this:

|base_url|/path
.. |base_url| replace:: http://localhost:8080

But the generated HTML is not what I want (doesn't include "/path" in the generated link):

<a href="http://localhost:8080"&gt;http://localhost:8080&lt;/a&gt;/path

Does anybody know how to work around this?

Answer 1

I can't help with your question, but you should know that what you are describing (an "API ... full of URL examples") is most definitely not REST. It's simply RPC. A RESTful API can only have one URI in it, the entry point. The other URIs are discovered via hypertext, but the client still can't know anything about how to assemble URIs or what the parts of the URI mean.

See this article by Roy Fielding, the man that specified REST in his dissertation.

Answer 2

You can write a Sphinx extension that creates a role like

:apilink:`path`

and generates the link from that. I never did this, so I can't help more than giving this pointer, sorry. You should try to look at how the various roles are implemented. Many are very similar to what you need, I think.

Answer 3

Ok, here's how I did it. First, apilinks.py (the Sphinx extension):

from docutils import nodes, utils

def setup(app):
    def api_link_role(role, rawtext, text, lineno, inliner, options={},
                      content=[]):
        ref = app.config.apilinks_base + text
        node = nodes.reference(rawtext, utils.unescape(ref), refuri=ref,
                               **options)
        return [node], []
    app.add_config_value('apilinks_base', 'http://localhost/', False)
    app.add_role('apilink', api_link_role)

Now, in conf.py, add 'apilinks' to the extensions list and set an appropriate value for 'apilinks_base' (otherwise, it will default to 'http://localhost/'). My file looks like this:

extensions = ['sphinx.ext.autodoc', 'apilinks']
# lots of other stuff
apilinks_base = 'http://host:88/base/'

Usage:

:apilink:`path`

Output:

<a href="http://host:88/base/path"&gt;http://host:88/base/path&lt;/a&gt;