Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS: Improve docs related to text exclusion #187

Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 30 additions & 19 deletions docs/use.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,36 @@
This section describes major ways to use and control `sphinx-copybutton`'s behavior.

(configure-copy-text)=

## Automatic exclusion of prompts from the copies

The Sphinx code highlighter, Pygments, tags the prompts (`>>>`, `...`,
`In [1]:`, `$`) of console sessions, and sphinx by default excludes
prompts from being selectable. Sphinx-copybutton can follows this
default with the following setting. This setting is not the default,
because it conflicts with the backwards compatibility of the other
following manually-selectable exclude options:
```{code-block} python
copybutton_exclude = '.linenos, .gp'
```

Add `.go` to the excludes and you will not copy console output,
either.

For automatic exclusion, use the right highlight language:
`pythonconsole` instead of `python`, `console` instead of `bash`,
`ipythonconsole` instead of `ipython`, etc.

This setting can also be used to exclude arbitrary css classes from
being copied. By default `.linenos` are excluded. `.linenos` is the
Sphinx default for line numbers, `.gp` is the Pygments class for the
prompts, and `.go` is the class for console outputs.

This setting conflicts with most of pattern-based copy-selection
settings below, so should not be used with them. This will hopefully
be improved in the future.
choldgraf marked this conversation as resolved.
Show resolved Hide resolved


## Strip and configure input prompts for code cells

By default, `sphinx-copybutton` will copy the entire contents of a code
Expand Down Expand Up @@ -366,22 +396,3 @@ button.copybtn {
See the [Sphinx documentation on custom CSS for more information](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).

[regex101]: https://regex101.com


## Exclude text from being copied

You may exclude elements matching CSS selectors from being copied by
specifying the `copybutton_exclude` option in ``conf.py``. For
example, a viewer usually doesn't want to copy the line numbers, and
CSS provides a way to exclude this. This option implements that
option for sphinx-copybutton as well.


```{code-block} python
copybutton_exclude = '.exclude_me'
```
By default `.linenos, .gp` are excluded. If you specify the
`copybutton_exclude` option it will replace the default. `.linenos`
is the Sphinx default for line numbers, and `.gp` is Pygments (the
default highlighter of Sphinx) for "prompt", e.g. `$` in a
shell-session. `.gp` is excluded in upstream Sphinx by default.