is there any way to render content in italics in a code block?

is there any way to render content in italics in a code block?

[Robert P. J. Day]

  one aspect of sphinx that gripes my wagger is that there does not
seem to be any easy way to tag something in italics in a code block.

here:

https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html

the code line:

 $ bitbake target

really needs the word "target" in italics to show that it's meant to
be replaced. and, no, this isn't minor nitpicking -- the whole section
on overrides desperately needs to be able to show what things a
developer is meant to replace.

  is there any way to do this?

rday

Re: [docs] is there any way to render content in italics in a code block?

[Antonin Godard]

On Thu Jan 8, 2026 at 10:33 PM CET, Robert P. J. Day wrote:
>
>   one aspect of sphinx that gripes my wagger is that there does not
> seem to be any easy way to tag something in italics in a code block.
>
> here:
>
> https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html
>
> the code line:
>
>  $ bitbake target
>
> really needs the word "target" in italics to show that it's meant to
> be replaced. and, no, this isn't minor nitpicking -- the whole section
> on overrides desperately needs to be able to show what things a
> developer is meant to replace.
>
>   is there any way to do this?

I don't know but the best bet would be to find a lexer capable of doing this in
here: https://pygments.org/docs/lexers/
As those are the ones used by Sphinx.

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] is there any way to render content in italics in a code block?

[Quentin Schulz]

Hi Robert,

On 1/8/26 10:33 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
>    one aspect of sphinx that gripes my wagger is that there does not
> seem to be any easy way to tag something in italics in a code block.
> 
> here:
> 
> https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html
> 
> the code line:
> 
>   $ bitbake target
> 
> really needs the word "target" in italics to show that it's meant to
> be replaced. and, no, this isn't minor nitpicking -- the whole section
> on overrides desperately needs to be able to show what things a
> developer is meant to replace.
> 
>    is there any way to do this?
> 

Not that I know of.

Another option is to follow conventions from manpages for example or 
something people are most familiar with.

bitbake [target]...

maybe? I'm not versed in manpages.

Also, you can simply specify after the code-block what must be changed 
by the user. It doesn't *have* to be a technical solution.

code-blocks have :emphasize-lines: maybe there's room for adding 
emphasize-columns or something like that such that we can specify what 
to highlight in a line.

Cheers,
Quentin

Re: [docs] is there any way to render content in italics in a code block?

[Robert P. J. Day]

On Thu, 15 Jan 2026, Quentin Schulz wrote:

> Hi Robert,
>
> On 1/8/26 10:33 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> >
> >    one aspect of sphinx that gripes my wagger is that there does not
> > seem to be any easy way to tag something in italics in a code block.
> >
> > here:
> >
> > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html
> >
> > the code line:
> >
> >   $ bitbake target
> >
> > really needs the word "target" in italics to show that it's meant to
> > be replaced. and, no, this isn't minor nitpicking -- the whole section
> > on overrides desperately needs to be able to show what things a
> > developer is meant to replace.
> >
> >    is there any way to do this?
> >
>
> Not that I know of.
>
> Another option is to follow conventions from manpages for example or something
> people are most familiar with.
>
> bitbake [target]...
>
> maybe? I'm not versed in manpages.
>
> Also, you can simply specify after the code-block what must be changed by the
> user. It doesn't *have* to be a technical solution.
>
> code-blocks have :emphasize-lines: maybe there's room for adding
> emphasize-columns or something like that such that we can specify what to
> highlight in a line.

  there is (sort of) a way to do this, it's with a "parsed-literal"
block, not a "code-block"

.. parsed-literal::
   ... stuff ...

- for italics, surround text with one asterisk
- for bold, surround text with two asterisks

my only nitpick is that what is rendered in italics also looks bolded.
anyway, probably not worth agonizing over this.

rday

Re: [docs] is there any way to render content in italics in a code block?

[Quentin Schulz]

Hi Robert,

On 1/15/26 4:55 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Thu, 15 Jan 2026, Quentin Schulz wrote:
> 
>> Hi Robert,
>>
>> On 1/8/26 10:33 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
>>>
>>>     one aspect of sphinx that gripes my wagger is that there does not
>>> seem to be any easy way to tag something in italics in a code block.
>>>
>>> here:
>>>
>>> https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html
>>>
>>> the code line:
>>>
>>>    $ bitbake target
>>>
>>> really needs the word "target" in italics to show that it's meant to
>>> be replaced. and, no, this isn't minor nitpicking -- the whole section
>>> on overrides desperately needs to be able to show what things a
>>> developer is meant to replace.
>>>
>>>     is there any way to do this?
>>>
>>
>> Not that I know of.
>>
>> Another option is to follow conventions from manpages for example or something
>> people are most familiar with.
>>
>> bitbake [target]...
>>
>> maybe? I'm not versed in manpages.
>>
>> Also, you can simply specify after the code-block what must be changed by the
>> user. It doesn't *have* to be a technical solution.
>>
>> code-blocks have :emphasize-lines: maybe there's room for adding
>> emphasize-columns or something like that such that we can specify what to
>> highlight in a line.
> 
>    there is (sort of) a way to do this, it's with a "parsed-literal"
> block, not a "code-block"
> 
> .. parsed-literal::
>     ... stuff ...
> 

This could be an option but only for BitBake snippets where we cannot 
have syntax highlighting anyway.

I *guess* we could afford this for shell/console snippets too, provided 
there's no console output. How does this work with the copybutton if we 
have a prompt in a parsed-literal? Maybe we'll need to get rid of 
prompts as well.

Also, maybe we want to have a look at how sphinxawesome-theme 
implemented emphasize-text for code-blocks, maybe something we can 
implement on our side as well (and have multiple entries for 
emphasize-text?). (MIT licensed, don't know if it's compatible with what 
we have in yocto-docs). c.f. 
https://sphinxawesome.xyz/demo/code-blocks/#highlight-placeholders-in-code-blocks

Cheers,
Quentin

Re: [docs] is there any way to render content in italics in a code block?

[Robert P. J. Day]

On Thu, 15 Jan 2026, Quentin Schulz wrote:

> Hi Robert,
>
> On 1/15/26 4:55 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> > On Thu, 15 Jan 2026, Quentin Schulz wrote:
> >
> > > Hi Robert,
> > >
> > > On 1/8/26 10:33 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> > > >
> > > >     one aspect of sphinx that gripes my wagger is that there does not
> > > > seem to be any easy way to tag something in italics in a code block.
> > > >
> > > > here:
> > > >
> > > > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-execution.html
> > > >
> > > > the code line:
> > > >
> > > >    $ bitbake target
> > > >
> > > > really needs the word "target" in italics to show that it's meant to
> > > > be replaced. and, no, this isn't minor nitpicking -- the whole section
> > > > on overrides desperately needs to be able to show what things a
> > > > developer is meant to replace.
> > > >
> > > >     is there any way to do this?
> > > >
> > >
> > > Not that I know of.
> > >
> > > Another option is to follow conventions from manpages for example or
> > > something
> > > people are most familiar with.
> > >
> > > bitbake [target]...
> > >
> > > maybe? I'm not versed in manpages.
> > >
> > > Also, you can simply specify after the code-block what must be changed by
> > > the
> > > user. It doesn't *have* to be a technical solution.
> > >
> > > code-blocks have :emphasize-lines: maybe there's room for adding
> > > emphasize-columns or something like that such that we can specify what to
> > > highlight in a line.
> >
> >    there is (sort of) a way to do this, it's with a "parsed-literal"
> > block, not a "code-block"
> >
> > .. parsed-literal::
> >     ... stuff ...
> >
>
> This could be an option but only for BitBake snippets where we cannot have
> syntax highlighting anyway.
>
> I *guess* we could afford this for shell/console snippets too, provided
> there's no console output. How does this work with the copybutton if we have a
> prompt in a parsed-literal? Maybe we'll need to get rid of prompts as well.
>
> Also, maybe we want to have a look at how sphinxawesome-theme implemented
> emphasize-text for code-blocks, maybe something we can implement on our side
> as well (and have multiple entries for emphasize-text?). (MIT licensed, don't
> know if it's compatible with what we have in yocto-docs). c.f.
> https://sphinxawesome.xyz/demo/code-blocks/#highlight-placeholders-in-code-blocks

  it's not a high priority, it would just have been handy if it were
easy.

rday