docs/use: Improve docs

- Improves #185 by documenting things, but there are likely better
  fixes later.
- Does not fix that issue, just makes it more clear in the short term.
- Review: worth a read to make sure it isn't too confusing.

Author: rkdarst

docs/use.md

@@ -3,6 +3,33 @@
 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 follows this
+default.  For automatic exclusion, use the right highlight language:
+`pythonconsole` instead of `python`, `console` instead of `bash`,
+`ipythonconsole` instead of `ipython`, etc.
+
+This is controlled via the `copybutton_exclude` setting.  If you want
+to also exclude the output from commands from being copied, you can set:
+
+```{code-block} python
+copybutton_exclude = '.linenos, .gp, .go'
+```
+
+This setting can also be used to exclude arbitrary css classes from
+being copied.  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 the
+Pygments class for the prompts.  `.go` is the console outputs.
+
+**This setting should be disabled (set to ``.linenos``) when using
+custom specifications as described below.**
+
+
 ## Strip and configure input prompts for code cells
 
 By default, `sphinx-copybutton` will copy the entire contents of a code
@@ -35,6 +62,13 @@ use the following configuration:
 copybutton_prompt_text = ">>> "
 ```
 
+This does *not* play nicely with the automatic exclusion, so for this,
+and most of the other settings on this page, you should also set the
+following to disable language-based exclusion:
+```python
+copybutton_exclude = '.linenos'
+```
+
 ### Using regexp prompt identifiers
 
 If your prompts are more complex than a single string, then you can use a regexp to match with.
@@ -366,22 +400,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.