sphinx_roles

A set of reStructuredText roles for Sphinx compatibility

To install, run nikola plugin -i sphinx_roles

This plugin adds reStructuredText roles and directives for Sphinx compatibility.

Currently supported:

  • pep: An enhanced :pep: role with support for anchors, like Sphinx's
  • ref: Cross references for arbitrary locations (see the sphinx docs). Limited to links inside a single document.
  • rfc: An enhanced :rfc: role with support for anchors, like Sphinx's
  • term: Reference to a term in the glossary
  • option: Reference to a option defined using the option directive
  • eq: Reference to a equation defined in a math directive's label option.
  • math: A Math directive that supports a :label: option like Sphinx's

The following are "semantic markup", they produce a HTML element with an extra CSS class for styling. The description is from the Sphinx docs.

  • abbr: abbreviations with explanations
  • command: The name of an OS-level command, such as rm
  • dfn: Mark the defining instance of a term in the text. (No index entries are generated.) [Remember Nikola has no indexes anyway]
  • kbd: Mark a sequence of keystrokes.
  • mailheader: The name of an RFC 822-style mail header.
  • makevar: The name of a make variable.
  • manpage: A reference to a Unix manual page including the section.
  • mimetype: The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone).
  • newsgroup: The name of a Usenet newsgroup.
  • program: The name of an executable program.
  • regexp: A regular expression. Quotes should not be included.
  • samp: A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part.
  • file: The name of a file or directory. Within the contents, you can use curly braces to indicate a “variable” part
  • menuselection: Menu selections should be marked using the menuselection role. This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence. The names of individual selections should be separated by -->.
  • guilabel: Labels presented as part of an interactive user interface should be marked using guilabel.

This plugin also implementes Sphinx's extlinks extension which lets you create "shortcuts" to URLs that follow a pattern. You need to declare the patterns in conf.py:

EXTLINKS = {'issue': ('https://bitbucket.org/birkenfeld/sphinx/issue/%s',
                      'issue ')}

Which will create this link issue 123 out of this:

:issue:`123`

For more details see the sphinx docs for extlinks.

It also implements the following paragraph-level markup from Sphinx:

  • versionadded
  • versionchanged
  • deprecated
  • centered
  • hlist -- Needs the user to define a hlist class in CSS that removes table borders to look good.
  • seealso -- Needs the user to define a seealso class in CSS to change the look of the admonition.

And finally, there is limited support for:

  • glossary -- Partially implemented: the term role only works in the same file as the glossary, and it doesn't support multiple terms per definition.
  • option -- Flaky, links from the option role don't work across files.

Issues? Questions?

You can report issues with this plugin and request help via GitHub Issues.