sphinxnotes-comboroles#

Sphinx extension for composing multiple roles.

Documentation: https://sphinx.silverrainz.me/comboroles
Source: https://github.com/sphinx-notes/comboroles
Changelog: https://sphinx.silverrainz.me/comboroles/changelog.html
Tracker: https://github.com/sphinx-notes/comboroles/issues
Download: https://pypi.org/project/sphinxnotes-comboroles/#files

Introduction#

The extension allows users to create roles composited by multiple roles.

As we know, reStructuredText does not yet support nested inline markups, so text like “bold code” or “italic link” doesn’t render as expected. With the extension, we make nested inline markups possible by compositing roles:

``bold code``	`bold code`	❌
:strong_literal:`bold code`	`bold code`	✔️
`https://example.com`	https://example.com	❌
:parsed_emphasis:`https://example.com`	https://example.com	✔️

Getting Started#

Note

We assume you already have a Sphinx documentation, if not, see Getting Started with Sphinx.

First, downloading extension from PyPI:

$ pip install sphinxnotes-comboroles

Then, add the extension name to extensions configuration item in your conf.py:

extensions = [
          # …
          'sphinxnotes.comboroles',
          # …
          ]

To create a “bold code” role that same as described in Introduction, Continue to add the following configuration, which tells the extension to composite roles strong (markup: **foo**) and literal (markup: ``foo``) into a new role strong_literal:

comboroles_roles = {
    'strong_literal': ['strong', 'literal'],
}

Then you can use it:

:strong_literal:`bold code`

bold code

See Usage for more details.

Contents#

Contents

The Sphinx Notes Project#

The project is developed by Shengyu Zhang, as part of The Sphinx Notes Project.

The Sphinx Notes Project