Using raw directive to change background color of code-block affects later blocks as well

[pique-b]

Describe the bug

I am using the following to change background color in a particular code-block as below:

   .. raw:: latex

      \definecolor{VerbatimColor}{rgb}{1,0.96,0.932} % Background color

   .. code-block:: html
      :caption: An example of using code block in raw directive

      'sphinxsetup': 'verbatimwithframe=true, VerbatimColor={RGB}{255,247,0} # Produces background color across doc

The problem that I am encountering is that all subsequent code-blocks too are getting affected by the above change. In my conf.py I have added:

    'sphinxsetup': 'verbatimwithframe=true, VerbatimColor={RGB}{255,247,0}, verbatimwrapslines=true, verbatimborder=1pt, VerbatimBorderColor={rgb}{0.648,0.165,0.165}',

and this takes effect in all the pages (as can be expected).

How to Reproduce

Using .. raw:: directive to change background color of a code block locally to override setting in conf.py.

latex_elements = {

'preamble': r'''

\usepackage[svgnames]{xcolor}

    ''',
'sphinxsetup': 'verbatimwithframe=true, VerbatimColor={RGB}{255,247,0}, verbatimwrapslines=true, verbatimborder=1pt, VerbatimBorderColor={rgb}{.648,.165,.165}',
}

Environment Information

Sphinx v7.2.6
macOS 10.12.6 (Sierra)
Python 3.9
Tex Live 2023

Sphinx extensions

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.imgmath',
              
]

Additional context

I have two problems to solve:

1. In order to stop the local settings from propagating, I have had to define another segment of .. raw:: directive to change it back to those defined in conf.py (as stated above).

   Is there a way to stop this behavior (i.e. when a local setting propagates to subsequent sections in the document), other than the hack I am currently employing?

2. Is there a way to carry out a local setting for borders? As in, how do I invoke the border frame (verbatimwithframe) and width (verbatimborder) settings locally (which I am currently doing in conf.py settings)?

[jfbu]

I have two problems to solve:

1. In order to stop the local settings from propagating, I have had to define another segment of `.. raw::` directive to change it back to those defined in `conf.py` (as stated above).
   _Is there a way_ to stop this behavior (i.e. when a local setting propagates to subsequent sections in the document),  other than the hack I am currently employing?

At this time apart from your method and trying hard not to try to think of various hacks the only variant I see is to do:

.. raw:: latex

   \begingroup
   <do your changes>

and insert

.. raw:: latex

   \endgroup

after

2. Is there a way to carry out a local setting for **borders**? As in, how do I invoke the border frame (`verbatimwithframe`) and width (`verbatimborder`) settings _locally_ (which I am **currently** doing in `conf.py` settings)?

Yes you can use raw directive to inject usage of \sphinxsetup LaTeX command

.. raw:: latex

   \begingroup
   \sphinxsetup{verbatimborder=2pt, pre_border-top-width=10pt,
                pre_background-TeXcolor=blue!10, pre_border-TeXcolor=red}



.. code-block:: python

   def foo(x):
       return x

.. raw:: latex

   \endgroup

.. this will again use conf.py settings:



.. code-block:: python

   def foo(x):
       return x

[picnixz]

In the future, we could have some directives behaving like \begingroup and \endgroup but where we do not need to actually write them using .. raw. We already have this kind of approach for .. default-role so I think we could do a similar trick for a more general scope-restriction directive.

[jfbu]

@picnixz users can already employ container directives. So user only need to define in the latex_elements['preamble'] the suitable sphinxclass<containernamehere> environment. Using therein \sphinxsetup to modify the entities which are configured via latex_elements['sphinxsetup'] globally in conf.py.

Pros:

• if you want to change style locally why only for one builder? So it is good to have same mark-up in source for all builders; with custom things either in CSS or added LaTeX preamble as explained above.

Cons:

• if your goal is only one builder, indentation from directive may be visually distracting.

[picnixz]

Oh I wasn't aware of the container directives (thoughsphinxclass<name> is hard to parse and I would have suggest using sphinxclass@name to make conf.py more readable). IIUC, the following is fine:

.. container:: foo

   .. code-block::
     
      whatever

On the other hand, we could maybe enhance the container directive with a "setup" phase:

.. container:: foo

   .. container-setup:: html

      setup for 'html' builder

   .. container-setup:: latex

      setup for 'latex' builder

   .. container-setup::

      setup for other builders (e.g., 'manpage')
   
   .. code-block::

      something rendered differently depending on the builder

[picnixz]

I think we can close this discussion since jfbu suggested a good alternative. In the future, we might open a real issue if we want an improvement.