diff --git a/docs/conf.py b/docs/conf.py index b6c8ba0..d633977 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,6 +100,8 @@ # # html_sidebars = {} +myst_enable_extensions = ["colon_fence"] + # CopyButton configuration copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " copybutton_prompt_is_regexp = True @@ -108,7 +110,14 @@ # Switches for testing but shouldn't be activated in the live docs # copybutton_only_copy_prompt_lines = False # copybutton_remove_prompts = False -# copybutton_image_path = "clipboard.svg" +# copybutton_image_path = "_static/clipboard.svg" # DEPRECATED: remove after next release # noqa: E501 +# copybutton_image_svg = """ +# # noqa: E501 +# +# # noqa: E501 +# +# +# """ # copybutton_selector = "div" diff --git a/docs/use.md b/docs/use.md index 33cd2d1..de0cbf4 100644 --- a/docs/use.md +++ b/docs/use.md @@ -235,16 +235,16 @@ encountered in a line. To use a different image for your copy buttons, do the following: -1. Place the image in the `_static/` folder of your site. -2. Set the `copybutton_image_path` variable in your `conf.py` to be the - path to your image file, **relative to** `_static/`. +1. Find the `` code for the image that you'd like to use. + For example, find an SVG from [Font Awesome](https://fontawesome.com/), [Tabler](https://tablericons.com/), or [Octicons](https://primer.style/octicons/). +2. Set the `copybutton_image_svg` variable in your `conf.py` to the SVG that you'd like to use. For example, if you wanted to use a **clipboard icon** instead of the default copy button icon, do the following: 1. Copy the `Clipboard Icon SVG` from [the Tabular icons pack](https://tablericons.com/). Here is the SVG for reference: - ```svg + ``` @@ -252,17 +252,18 @@ For example, if you wanted to use a **clipboard icon** instead of the default co ``` -2. Create a file at `_static/clipboard.svg` from your documentation root. - Paste in the SVG above into that file. - -3. Ensure that your `_static` folder is added to your `html_static_paths` configuration in Sphinx. - -4. Configure `sphinx_copybutton` to use this icon instead, via the following configuration: +2. Configure `sphinx_copybutton` to use this icon instead, via the following configuration: ```python # Note that we do not include `_static` # because the path should be *relative* to the static folder. - copybutton_image_path = "clipboard.svg" + copybutton_image_svg = """ + + + + + + """ ``` When you re-build your documentation, you should see this new icon in your copy buttons. @@ -288,27 +289,37 @@ added to them. ## Modify the copy button's CSS You can style the CSS of the copy button however you'd like by writing your own CSS with your Sphinx build. -To do so, add a CSS rule that uses the `.copybtn` selector and the CSS that you'd like to apply. - -For example, to make the copy button visible by default (not just when a code cell is hovered), do the following: +To do so, first create a custom CSS file and add it to your Sphinx build: 1. Create a `custom.css` file in the `_static/` folder of your documentation. - -2. Add the following rule to it: - - ```css - button.copybtn { - opacity: 1; - } - ``` - -3. Add the CSS file to Sphinx by ensuring that the following configuration exists in your `conf.py` file (see [the Sphinx documentation for more details](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)): +2. Add the CSS file to Sphinx by ensuring that the following configuration exists in your `conf.py` file (see [the Sphinx documentation for more details](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)): ```python html_static_path = ["_static"] html_css_files = ["custom.css"] ``` +Next you can add CSS rules that use the `.copybtn` selector to modify the behavior of the button. + +:::{admonition} example: button visibility +:class: tip +To make the copy button visible by default (not just when a code cell is hovered): + +```css +button.copybtn { + opacity: 1; +} +``` +::: + +:::{admonition} example: style the color of the button +```css +button.copybtn { + color: red; +} +``` +::: + 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 diff --git a/sphinx_copybutton/__init__.py b/sphinx_copybutton/__init__.py index 1597466..17cf77c 100644 --- a/sphinx_copybutton/__init__.py +++ b/sphinx_copybutton/__init__.py @@ -40,7 +40,19 @@ def add_to_context(app, config): config.html_context.update( {"copybutton_here_doc_delimiter": config.copybutton_here_doc_delimiter} ) - config.html_context.update({"copybutton_image_path": config.copybutton_image_path}) + + # Old image path deprecation + # REMOVE after next release + if config.copybutton_image_path: + path = Path(app.srcdir) / config.copybutton_image_path + logger.warning("copybutton_image_path is deprecated, use copybutton_image_svg") + if not path.exists(): + raise ValueError("copybutton_img_path does not exist") + if not path.suffix == ".svg": + raise ValueError("copybutton_img_path must be an SVG") + config.copybutton_image_svg = path.read_text() + + config.html_context.update({"copybutton_image_svg": config.copybutton_image_svg}) config.html_context.update({"copybutton_selector": config.copybutton_selector}) config.html_context.update( { @@ -66,9 +78,12 @@ def setup(app): app.add_config_value("copybutton_copy_empty_lines", True, "html") app.add_config_value("copybutton_line_continuation_character", "", "html") app.add_config_value("copybutton_here_doc_delimiter", "", "html") - app.add_config_value("copybutton_image_path", "copy-button.svg", "html") + app.add_config_value("copybutton_image_svg", "", "html") app.add_config_value("copybutton_selector", "div.highlight pre", "html") + # DEPRECATE THIS AFTER THE NEXT RELEASE + app.add_config_value("copybutton_image_path", "", "html") + # Add configuration value to the template app.connect("config-inited", add_to_context) diff --git a/sphinx_copybutton/_static/copybutton.css b/sphinx_copybutton/_static/copybutton.css index 5d29149..40eafe5 100644 --- a/sphinx_copybutton/_static/copybutton.css +++ b/sphinx_copybutton/_static/copybutton.css @@ -3,7 +3,7 @@ button.copybtn { position: absolute; display: flex; top: .3em; - right: .5em; + right: .3em; width: 1.7em; height: 1.7em; opacity: 0; @@ -13,17 +13,22 @@ button.copybtn { border: none; outline: none; border-radius: 0.4em; - border: #e1e1e1 1px solid; - background-color: rgb(245, 245, 245); + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; } button.copybtn.success { border-color: #22863a; + color: #22863a; } -button.copybtn img { - width: 100%; - padding: .2em; +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; } div.highlight { @@ -79,3 +84,10 @@ div.highlight { transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); transition-delay: .5s; } + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/sphinx_copybutton/_static/copybutton.js_t b/sphinx_copybutton/_static/copybutton.js_t index 3b93e34..92e6739 100644 --- a/sphinx_copybutton/_static/copybutton.js_t +++ b/sphinx_copybutton/_static/copybutton.js_t @@ -55,7 +55,25 @@ if (doc_url_root == '#') { doc_url_root = ''; } -const path_static = `${doc_url_root}_static/`; +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = `{{ copybutton_image_svg }}`; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} /** * Set up copy/paste for code blocks @@ -94,9 +112,8 @@ const temporarilyChangeTooltip = (el, oldText, newText) => { // Changes the copy button icon for two seconds, then changes it back const temporarilyChangeIcon = (el) => { - img = el.querySelector("img"); - img.setAttribute('src', `${path_static}check-solid.svg`) - setTimeout(() => img.setAttribute('src', `${path_static}{{ copybutton_image_path }}`), 2000) + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, 2000) } const addCopyButtonToCodeCells = () => { @@ -115,7 +132,7 @@ const addCopyButtonToCodeCells = () => { const clipboardButton = id => `${messages[locale]['copy_to_clipboard']} + ${iconCopy} ` codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) })