Re: [docs] [PATCH 02/10] docs: copy only the command from a console block

[Trevor Woerner <twoerner@gmail.com>]

On Tue 2026-09-22 @ 02:20:00 PM, Antonin Godard wrote:
> Hi,
> 
> On Tue Sep 22, 2026 at 4:03 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> > The copy button matches the literal "$ " prompt, so on a block prompted
> > any other way it matches nothing and falls back to copying every line,
> > output included. Match a pattern covering each prompt shape the manuals
> > use instead, and stop the mouse selecting the output, so both ways of
> > copying give the commands alone.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> >  documentation/conf.py                         | 21 ++++++++++++++++++-
> >  .../sphinx-static/theme_overrides.css         |  9 ++++++++
> >  2 files changed, 29 insertions(+), 1 deletion(-)
> >
> > diff --git a/documentation/conf.py b/documentation/conf.py
> > index 48d28a686807..ccec27e60165 100644
> > --- a/documentation/conf.py
> > +++ b/documentation/conf.py
> > @@ -242,4 +242,23 @@ intersphinx_mapping = {
> >  # -- sphinx_copybutton configuration -----------------------------------------
> >  
> >  # sphinx-copybutton configuration
> > -copybutton_prompt_text = "$ "
> > +# Strip the prompt from a copied line wherever the prompt cannot be
> > +# confused with content. The pattern is not scoped to console blocks, so
> > +# every alternative has to stay safe inside a BitBake or configuration
> > +# example as well; measured over the built manuals, each one matches only
> > +# lines the lexer itself marks as a prompt.
> > +#
> > +# A bare "#" is deliberately absent. It opens a root prompt, a comment and
> > +# a line of program output alike, and nothing distinguishes them - which is
> > +# why the root prompts are given a preamble before this is switched on.
> > +copybutton_prompt_text = "|".join((
> > +    r"^(?:\S+[@:]\S*)?\$\s+",   # "$ ", and "user@host:~$ "
> > +    r"^\S+[@:]\S*#\s+",         # "root@qemux86-64:~# ", a root prompt
> > +    r"^[A-Za-z]:\\[^>]*>\s*",   # "C:\WINDOWS\system32>", cmd.exe
> > +    r"^DISKPART>\s*",           # diskpart prints a prompt of its own
> > +    r"^pydevshell>\s+",         # bitbake -c pydevshell
> > +))
> > +copybutton_prompt_is_regexp = True
> > +copybutton_only_copy_prompt_lines = True
> > +copybutton_remove_prompts = True
> > +copybutton_line_continuation_character = "\\"
> > diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
> > index f9e067239b8e..1a439e9faf69 100644
> > --- a/documentation/sphinx-static/theme_overrides.css
> > +++ b/documentation/sphinx-static/theme_overrides.css
> > @@ -107,6 +107,15 @@ section#welcome-to-the-yocto-project-documentation p.caption {
> >     display: none;
> >  }
> >  
> > +/* Sphinx already excludes the prompt from a selection; do the same for the
> > +   output, so selecting a session block gives what the copy button gives */
> > +.highlight span.go {
> > +    user-select: none;
> > +    -webkit-user-select: none;
> > +    -moz-user-select: none;
> > +    -ms-user-select: none;
> > +}
> 
> This only works if the code-block uses the "console" lexer, though. Maybe say
> that in the comment.
> 
> But I think we don't want that. Copying outputs might be useful in some cases.
> And I trust the reader to be conscious enough to only select the command, not
> the output of the command (it's still nice not having the prompt selectable
> though).
> 
> I know this doesn't reflect 100% what the copy-button does but at least there's
> still the option to copy the output.

My preference would be that when the user copies, they only get the
command; my guess is that's what they need, because they want to try the
commands themselves. The output is something they might look at, but not
necessarily copy.

But I can see a case where they might want the output too. So I'm okay
with changing the behaviour if that's what you'd prefer: it is one
setting and one CSS rule, and both methods would then give the command
plus its output, with the prompt stripped in each case.

I have a much stronger opinion that the copybutton and mouse-selection
should work the same, regardless of which way we decide they should work.
First off, I don't think readers are going to really notice there are two
ways to copy. But if they do notice, I think they would be surprised to
find they worked differently.

Either way, I think the conventions page ought to say so. It does not
mention copying at all today, and "Commands and prompts" is the natural
home for it: a sentence that the prompt is not part of the command, and
that neither way of copying includes it. I would rather send that once
we have settled which behaviour we want, so the page does not describe
something that is not true yet - which is the mistake I made by sending
that page ahead of the series in the first place.

> Thanks,
> Antonin