How To Document A Single Space Character Within A String In Rest/sphinx?

I've gotten lost in an edge case of sorts. I'm working on a conversion of some old plaintext documentation to reST/Sphinx format, with the intent of outputting to a few formats (in

Solution 1:

Try using the unicode character codes. If I understand your question, this should work.

Here is a "|space|"and a non-breaking space (|nbspc|)

.. |space| unicode:: U+0020 .. space
.. |nbspc| unicode:: U+00A0 .. non-breaking space

You should see:

Here is a “ ” and a non-breaking space ( )

Solution 2:

I was hoping to get out of this without needing custom code to handle it, but, alas, I haven't found a way to do so. I'll wait a few more days before I accept this answer in case someone has a better idea. The code below isn't complete, nor am I sure it's "done" (will sort out exactly what it should look like during our review process) but the basics are intact.

There are two main components to the approach:

1. introduce a char role which expects the unicode name of a character as its argument, and which produces an inline description of the character while wrapping the character itself in an inline literal node.
2. modify the text-wrapper Sphinx uses so that it won't break at the space.

Here's the code:

classTextWrapperDeux(TextWrapper):
    _wordsep_re = re.compile(
    r'((?<!`)\s+(?!`)|'# whitespace not between backticksr'(?<=\s)(?::[a-z-]+:)`\S+|'# interpreted text startr'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|'# hyphenated wordsr'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))')   # em-dash    @propertydefwordsep_re(self):
        return self._wordsep_re

defchar_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    """Describe a character given by unicode name.

    e.g., :char:`SPACE` -> "char:` `(U+00020 SPACE)"
    """try:
        character = nodes.unicodedata.lookup(text)
    except KeyError:
        msg = inliner.reporter.error(
            ':char: argument %s must be valid unicode name at line %d' % (text, lineno))
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    app = inliner.document.settings.env.app
    describe_char = "(U+%05X %s)" % (ord(character), text)
    char = nodes.inline("char:", "char:", nodes.literal(character, character))
    char += nodes.inline(describe_char, describe_char)
    return [char], []

defsetup(app):
    app.add_role('char', char_role)

The code above lacks some glue to actually force the use of the new TextWrapper, imports, etc. When a full version settles out I may try to find a meaningful way to republish it; if so I'll link it here.

Markup: Starting character is the :char:`SPACE` which has the value 0.

It'll produce plaintext output like this: Starting character is the char:` `(U+00020 SPACE) which has the value 0.

And HTML output like: Starting character is the <span>char:<code class="docutils literal"> </code><span>(U+00020 SPACE)</span></span> which has the value 0.

The HTML output ends up looking roughly like: Starting character is the char:(U+00020 SPACE) which has the value 0.