How to set color for a single word

[madum31]

Hi,

I wanted to use the atsphinx.color_text package to use ":color:" syntax in reStructuredText for keywords.
Unfortunately, rinohtype does not render colored text in PDF output.

Do I missed something or is there another way to perform such functionality ?

Thanks

[brechtm]

Sphinx extensions need to implement support for each builder. The atsphinx-color-text extension only supports HTML output. You can however hack in support for rinohtype by adding the following to tour conf.py:

# -- rinohtype implementation for atsphinx-color-text ---------------------

from rinoh.color import HexColor
from rinoh.frontend.rst.nodes import Inline
from rinoh.text import TextStyle


class RinohColorText(Inline):
    node_name = 'ColorText'

    def build_styled_text(self):
        _, color = self.attributes['style'].split(': #')
        return self.process_content(style=TextStyle(font_color=HexColor(color)))

Often it is possible to make Sphinx extensions independent of the builder, but extension authors are typically not aware of this. See #201 (comment) (and the comments following it) for more information on that. This particular extensions would still need adding styles to the style sheet, however.

Note that you can also color text by declaring custom roles as proposed in this StackOverflow item: https://stackoverflow.com/questions/3702865/sphinx-restructuredtext-set-color-for-a-single-word. For rinohtype, you would need to define extra styles in the style sheet to handle these roles. Let me know if you want more info.

Finally, I would recommend against explicitly coloring text. reStructuredText is designed to be describe semantics, not representation. For example, you have the built-in :emphasis: and :strong: roles, instead of italic and bold roles. It is up to the builder / style sheet to map semantics to representation.

[madum31]

Thanks for your answer and advices.

I confess, i didn't spent enough time to look for a proper solution to my request.
and the need of coloring text was not completly and clearily explained:
In fact I need to highlight with specific style/text color some keywords in the rest text.

I also found and tried :

• a potential adapted answer for this request using the sphinxcontrib-text-styles, but failed to give expected result.
• I also tried a possible solution, still failing PDF rendering.

Then I tried your solution but failed to get expected result (don't you have example with result ?)

Regarding the coloring text process, I completly agree with your standpoint of dissociating semantic from representation.
I appologyze, I'm a litle bit newbie discovering sphinx/rinohtype processing :-\

I'had a look on the Sphinx doc for adding new role.
This shows me some progress in the way I got keyword text modified.
Then I tried to set extra style parameters in the rhinohtype sphinx.rts file for [keyword] element but did not get expected result.

I'm now exploring how to set specific style for the keyword role.

Any comment are welcome ;-)

[brechtm]

No need to apologize!

Of course, the easiest solution would be if plugins like atsphinx.color_text and sphinxcontrib-text-styles would support rinohtype. You could kindly ask their authors if they would be interested in adding support for the rinoh builder. I could do it, but I'm already lacking the time to work on rinohtype itself, so I better not.

That said, using atsphinx.color_text should work if you add the code I provided to your conf.py. Without it, rendering the document Sphinx aborts with an exception when rendering the PDF. What happens at your side? Do you get to see an error?

As for an approach using text roles, you can define and use a new role in a reStructuredText file (keyword.rst):

.. role:: keyword

This is a :keyword:`schnitzel`.

A role will add a class to the corresponding element in the document tree. You can use this class to define a style in the stylesheet (keyword.rts) with a rule that matches the element:

[STYLESHEET]
base=sphinx

[table of contents section]
hide = true

[keyword : StyledText(has_class='keyword')]
font_slant = italic
font_weight = bold
font_color = #b33

Note that adding a style [keyword] will not work as that would require the default matcher to define the keyword style. Since this a new custom style, you need to specify the selector (StyledText(has_class='keyword')]) yourself.

You can render this example from the command line:

rinoh --stylesheet keyword.rts keyword.rst

This is not yet documented in the rinohtype manual, so it would be difficult to figure out. Custom selectors are documented, but the has_class and has_classes keywords aren't (yet).

BTW, you can get a view on the internals:

• reStructuredText document tree: rst2pseudoxml.py keyword.rst)
• rinohtype document tree: keyword.stylelog (output during rendering)

[madum31]

I finally succeed to get get colored text with the solution you proposed associated with atsphinx.color_text package.

Then I tried to extend what you provided for TextStyle
return self.process_content(style=TextStyle(font_color=HexColor(color)

to add bold and italic style to colored text :
return self.process_content(style=TextStyle(font_color=HexColor(color),font_slant='italic',font_weight='bold'))

Unfluckily failed and got following Traceback :

Lib\site-packages\rinoh\font\style.py", line 97, in nearest
        offset = (1 if value > cls.center else -1) * cls.offset
                       ^^^^^^^^^^^^^^^^^^
    TypeError: '>' not supported between instances of 'str' and 'int'

I didn't explore deeper text role approach for now because I don't have enough knowledge on sphinx / rinohtype principles and working.
Thanks

[brechtm]

The font_slant and font_weight Text style arguments expect FontSlant and FontWeight instances instead of strings. In that sense, it is easier to map the atsphinx styles (hex color codes) to rinohtype styles. To do that, assign the color variable to the style attribute of process_content. Now you can match those styles in the stylesheet with a custom selector:

[color-text-red : StyledText('ff0000')]
...

Typing this on my phone, so it's a bit basic. But I hope it's clear.

[brechtm]

Here's a more complete implementation of this suggestion.

Add this to your conf.py:

# -- rinohtype implementation for atsphinx-color-text ---------------------

from atsphinx.color_text import COLORS
from rinoh.frontend.rst.nodes import Inline
from rinoh.text import StyledText
from rinoh.stylesheets import matcher


class RinohColorText(Inline):
    node_name = 'ColorText'

    def build_styled_text(self):
        # set style on the StyledText, so that matchers can pick it up
        _, hex_color = self.attributes['style'].split(': #')
        return self.process_content(style=f'color-text-{hex_color}')


# define styles for all colors
for name, hex_color in COLORS.items():
    matcher[f'color-text-{name}'] = StyledText.like(style=f'color-text-{hex_color[1:]}')

stylesheet.rst:

[color-text-black]
font_color=#000000

[color-text-silver]
font_color=#c0c0c0

[color-text-gray]
font_color=#808080

[color-text-white]
font_color=#ffffff

[color-text-maroon]
font_color=#800000

[color-text-red]
font_color=#ff0000

[color-text-purple]
font_color=#800080

[color-text-fuchsia]
font_color=#ff00ff

[color-text-green]
font_color=#008000

[color-text-lime]
font_color=#00ff00

[color-text-olive]
font_color=#808000

[color-text-yellow]
font_color=#ffff00

[color-text-navy]
font_color=#000080

[color-text-blue]
font_color=#0000ff

[color-text-teal]
font_color=#008080

[color-text-aqua]
font_color=#00ffff

You need to configure Sphinx to find your stylesheet.rts. In conf.py:

rinoh_documents = [{
    'doc': master_doc,          # top-level file (index.rst)
    'target': 'manual',          # output (manual.pdf)
    'title': project,           # document title
    'author': author,           # document author
    'template': 'template.rtt'  # document template (references stylesheet.rts)
}]

template.rtt:

[TEMPLATE_CONFIGURATION]
name=my-template
template=book
stylesheet=stylesheet.rts

You can now adjust stylesheet.rts to your liking.

[madum31]

Many thanks for your multiple suggestions.
I finally found the origin of my original issue :

• I used the keyword "keyword" for tagging specific role.
• This does not work (probably "keyword" is excluded for extended elements I used) with the complete Sphinx environment with extensions I worked with (see attached PDF screenshot kwd_full_config.jpg).
  
• So I checked with a reduced configuration (specifically for conf.py) as mentionned below and got normal output as expected initilally (see attached screenshot kwd_reduced_config.jpg)
  

So I tried the following configuration (index.rst) :

.. role:: keyword

.. role:: keywrd

This is a :keyword:`keyword`.

This is a :keywrd:`keyword`.

With the folowing content in RinohType Style file (index.rts) :

[keyword : StyledText(has_class='keyword')]
base = None
font_slant = italic
font_weight = bold
font_color = #ffa500

[keywrd : StyledText(has_class='keywrd')]
base = None
font_weight = bold
font_slant = italic
font_color=#ff0000

and following template file (index.rtt) :

[TEMPLATE_CONFIGURATION]
name = index
template = book
stylesheet = index.rts

No particular conf.py addition from initial setting (no atsphinx-color-text extension package reference or added python code)
Just :

rinoh_documents = [dict(doc='index',
                        target='index',
                        template='index.rtt')]

Then running rinoh :
rinoh --stylesheet index.rts index.rst

So I will use the "keywrd" keyword for the role I need to guarantee uniqueness and functionalities perenity.

Many thanks for your help and advices,
best regards,
Martial

[brechtm]

Ah, indeed, the :keyword: role is already defined by Sphinx for cross-referencing Python keywords. It would be nice if Sphinx would warn the user when they redefine the role.

No particular conf.py addition from initial setting (no atsphinx-color-text extension package reference or added python code) Just :

rinoh_documents = [dict(doc='index',
                        target='index',
                        template='index.rtt')]

Then running rinoh : rinoh --stylesheet index.rts index.rst

In case there is confusion here: the rinoh command line tool is independent of Sphinx. It does not require conf.py or use it when present. This also means that when rendering a document using rinoh, no Sphinx-defined roles or directives are supported, and hence the :keyword: role is not predefined.