3

I would like to create a sphinx role :config:`param` that appears as literal text config["param"] and at the same time is a link.

I've a basic running version:

def config_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    rendered = nodes.Text('config["{}"]'.format(text))

    rel_source = inliner.document.attributes['source'].split('/doc/', 1)[1]
    levels = rel_source.count('/')
    refuri = ('../' * levels +
              'tutorials/introductory/customizing.html#config')

    ref = nodes.reference(rawtext, rendered, refuri=refuri)
    return [nodes.literal('', '', ref)], []


def setup(app):
    app.add_role("config", config_role)
    return {"parallel_read_safe": True, "parallel_write_safe": True}

However, there are two issues:

  • The target of the link is in another part of the documentation. Therefore I have to create the refuri explicitly. Is is possible to use the link anchor somehow as one would do with :ref:`config` in .rst?
  • nodes.reference has the unwanted effect that the double-quotes are replaced by typographic quotes. Since it's in a literal bock, I'd rather keep the plain double quotes. Is this somehow possible?
Tim Hoffmann
  • 1,325
  • 9
  • 28
  • For typographical quotes, which version of Sphinx are you using? Do you have a setting of `html_use_smartypants=True` or `smartquotes = True` in your `conf.py`? – Steve Piercy Jun 20 '18 at 13:25
  • Sphinx 1.7.5. Neither of the both variables are defined in `conf.py`. – Tim Hoffmann Jun 20 '18 at 20:36
  • The [default value of `smartquotes` is `True`](http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes). You need to explicitly add it and set it to `False`. Sorry, I don't know about the main question about the role. I can't parse that question. – Steve Piercy Jun 20 '18 at 20:57
  • Thanks! Is there some way to temporarily turn that option off only for the reference node in my above code? – Tim Hoffmann Jun 22 '18 at 07:44
  • All configuration options may be overridden on the command line when invoking `sphinx-build` with a [`-D setting=value`](http://www.sphinx-doc.org/en/master/man/sphinx-build.html#id2) option. – Steve Piercy Jun 22 '18 at 09:22

0 Answers0