sphinx-doc / sphinx-doc/sphinx

Make the separator for the :guilabel: role a configurable character

Open
#7,006 6 comments 0 reactions 1 assignee View on GitHub

@jfbu is already working on this.

Since Jan 19, 2020.

builder:latex type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.

With #6738, the separator character 'TRIANGULAR BULLET' is not escaped anymore for unicode capable latex engines. Unfortunately, this depends on the font having this character. I use latex_engine = 'xelatex' and the Adobe Source Sans font family which does not have this character.

Describe the solution you'd like

I would like a configuration option to override the default character.

Describe alternatives you've considered

I currently use this code snippet in my conf.py:

def setup(app):
    '''
    modify the `menuselection` role to replace the default character
    `TRIANGULAR BULLET` with `RIGHTWARDS ARROW` as the font that we use
    does not have this character.
    '''
    from docutils.parsers.rst import roles
    from sphinx.roles import GUILabel

    class CustomMenu(GUILabel):
        def run(self):
            self.text = self.text.replace('-->', '\N{RIGHTWARDS ARROW}')
            return super().run()

    roles.register_local_role('menuselection', CustomMenu())

which works as I want, but it feels like a hack.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.