How to document a single space character in a string in reST / Sphinx?

Question

I got lost in the case of the edge. I am working on converting some old textual documentation into reST / Sphinx format, with the goal of outputting several formats from it (including HTML and text). Some of the documented functions are designed to work with bistro strings, and a common example inside them is a sentence similar to the following:Starting character is the blank " " which has the value 0.

I tried to write this as an inline literal in the following ways: Starting character is the blank `` `` which has the value 0.or Starting character is the blank :literal:` ` which has the value 0., but there are a few problems with how they work:

• reST syntax of objects in a space immediately inside the literal, and it is not recognized.
• The above can be “fixed” - it looks correct in HTML ( ) and in plain text ( " ") - with an inextricable space character inside the literal, but technically this is a lie in our case, and if the user copied this character, they will not copy what what they expect.
• The space can be wrapped in regular quotation marks, which allows you to correctly recognize the literal, and while the output in HTML is probably fine ( " "), in clear text it ends with double quotation marks as "" "".
• In both 2/3 above, if the literal falls on the boundary of the flow around, the plaintext writer (who uses textwrap) happily completes the inside of the literal and cuts off the space, because it is at the beginning / end of the line.

, - ; ?

Answer 1

, , , . , , - . , , "" ( , ), .

:

• char, , node.
• Sphinx , .

:

class TextWrapperDeux(TextWrapper):
    _wordsep_re = re.compile(
    r'((?<!`)\s+(?!`)|'                       # whitespace not between backticks
    r'(?<=\s)(?::[a-z-]+:)`\S+|'              # interpreted text start
    r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|'   # hyphenated words
    r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))')   # em-dash

    @property
    def wordsep_re(self):
        return self._wordsep_re

def char_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], []

def setup(app):
    app.add_role('char', char_role)

- , TextWrapper, .. , ; , .

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

: Starting character is the char:` `(U+00020 SPACE) which has the value 0.

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

HTML : - char: (U + 00020 SPACE), 0.

Answer 2

unicode. , .

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

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

:

"" ()