Add sphinx-copybutton for codeblock #12528

thoo · 2018-11-06T06:46:17Z

Close #12512
Using sphinx-copybutton extension to add a copybutton for the code block. It should look like this:

eamanu · 2018-11-06T12:26:16Z

I don't know sphinx-copybutton extension but, is this added automatically the button to whole code in the docs? or this have to added one by one?

rth

The generated docs are in https://37582-843222-gh.circle-artifacts.com/0/doc/index.html they look good.

This doesn't seem to work for prompt though,
i.e. when copying https://37582-843222-gh.circle-artifacts.com/0/doc/modules/linear_model.html#lars-lasso , >>> also get copied. Meaning one would need to first click on "hide prompt" then on copy, in which case I don't really see the advantage of this over a copy past. My assumption was that copy button would only copy the code not the output.

rth · 2018-11-06T12:34:27Z

doc/themes/scikit-learn/static/nature.css_t

+    top: 20px !important;
+    padding: 0px 4px 2px !important;
+    background: transparent no-repeat none !important;
+}


This is not included in the extension?

The naming is confusing here. The >>> prompt button is named as copybutton. I just try to re-arrange Hide prompts and output button. This is not the one I am adding.

eamanu · 2018-11-06T13:48:27Z

Great!! this is a good idea. But, IMO the prompt have to be hide by default. so this way, I can copy and paste quickly without pressing the hide button. Is this a configuration?

thoo · 2018-11-07T09:33:55Z

I agree. The prompt >>> and output should be filtered out when the code block is copied. I am looking into it.

qinhanmin2014 · 2018-11-09T03:15:05Z

Thanks for the PR. The bottom doesn't seems very useful for scikit-learn. We need to first hide the prompts and outputs. What's more, many examples cannot be executed at once (e.g, we don't use print in some examples, see the Examples section in https://37582-843222-gh.circle-artifacts.com/0/doc/modules/generated/sklearn.cluster.DBSCAN.html). Feel free to improve your PR or close it (since there's another -1 from rth I guess).

thoo · 2018-11-09T05:49:46Z

This should only copy codes and exclude outputs, and prompts. @eamanu Can you test it again? It works fine on Mac but I haven't tried it on other operating systems. This extension uses clipboard.js which is independent of Flash. So I assume it will work smoothly across different platforms. I also submitted the PR for sphinx-copybutton. As of now, we have to install it from pip install -e git+https://github.com/thoo/sphinx-copybutton.git@for_scikit_learn#egg=sphinx-copybutton.

eamanu · 2018-11-09T12:44:59Z

build_tools/circle/build_doc.sh

@@ -124,6 +124,7 @@ conda create -n $CONDA_ENV_NAME --yes --quiet python="${PYTHON_VERSION:-*}" \

 source activate testenv
 pip install sphinx-gallery
+pip install -e git+https://github.com/thoo/sphinx-copybutton.git@for_scikit_learn#egg=sphinx-copybutton


I don't know if that is a good solution.

Yeah I ended up placing css and js files under custom folder. So no python dependencies to install.

Thanks for the review.

eamanu · 2018-11-09T12:54:13Z

@qinhanmin2014 IMHO the copy button is a little "plus". This can not take much time.

eamanu · 2018-11-09T12:54:32Z

@thoo look for ci/circleci: python2 that fail

qinhanmin2014

Thanks, the PR itself looks very nice, but the main problem remains, i.e., many of our examples cannot be executed at once (e.g, we don't use print in some examples). I'll vote +1 and we need another +1.

thoo · 2018-11-10T02:15:53Z

@qinhanmin2014 Thanks for the review. I am confused about executing at once. I usually set InteractiveShell.ast_node_interactivity = "all" in jupyter notebook if I want to see all outputs and I thought that is the reason we don't have print in some examples ??

qinhanmin2014 · 2018-11-10T02:43:36Z

I usually set InteractiveShell.ast_node_interactivity = "all" in jupyter notebook if I want to see all outputs

Thanks, I'm aware of these ways and this is why I vote +1.

jnothman

Putting each of these files in the global theme is the wrong way to do modularity and encapsulation. Rather, like doc/sphinxext/sphinx_issues.py, the code should just be included as a whole unit and activated with the usual extensions mechanism. If we need to alter it, we can do that too, leaving appropriate notes.

jnothman · 2018-11-12T02:01:43Z

doc/themes/scikit-learn/static/js/sphinx_copybutton.js

@@ -0,0 +1,116 @@
+// Please see details at https://github.com/choldgraf/sphinx-copybutton


This is not sufficient according to https://github.com/choldgraf/sphinx-copybutton/blob/master/LICENSE:

"
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
"

jnothman · 2018-11-12T02:01:56Z

doc/conf.py

@@ -68,7 +68,7 @@
 source_suffix = '.rst'

 # The encoding of source files.
-#source_encoding = 'utf-8'
+# source_encoding = 'utf-8'


Please do not change unrelated things. It makes your contribution harder to review and may introduce merge conflicts to other pull requests.

jnothman · 2018-11-12T02:07:01Z

uX comments: * The "hide/show the prompts and output" tooltip is appearing when I hover the copy button. * The Copy tooltip should specify that it only copies the code.

thoo · 2018-11-12T05:10:34Z

@jnothman Thanks for the review. I agree it is better to be a separate extension like sphinx_issues.py .

The "hide/show the prompts and output" tooltip was tied to the whole code block and I wasn't sure it was on purpose or not when "prompts and output" button was added. It is not because of this PR. As you mention it, I will limit this tooltip only to the "prompts and output" button not to the whole code block.

thoo · 2018-11-12T23:09:54Z

@jnothman Could you re-review? I added sphinx_copybutton at sphinxext as a local extension.

jnothman · 2018-11-13T07:39:07Z

doc/themes/scikit-learn/static/css/sphinx_copybutton.css

@@ -0,0 +1,103 @@
+/*


Why can't the CSS be kept under sphinxext/sphinx_copybutton as it would be if installed as a separate package?

Sure. All the files are now under sphinxext/sphinx_copybutton.

jnothman · 2018-11-14T10:32:28Z

doc/conf.py

@@ -22,6 +22,9 @@
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('sphinxext'))
+# Path for sphinx_copybutton ext.
+sys.path.insert(0, os.path.abspath(


This should not be necessary if there is a file sphinxext/sphinx_copybutton/__init__.py

jnothman

No I meant that like the original package, the primary code should be in sphinx_copybutton/__init__.py. if there are any worthwhile updates to the original package we would be able to simply copy it in.

thoo · 2018-11-15T00:54:51Z

Ah I see. Done.

rth reviewed Nov 6, 2018

View reviewed changes

eamanu suggested changes Nov 9, 2018

View reviewed changes

eamanu approved these changes Nov 9, 2018

View reviewed changes

qinhanmin2014 approved these changes Nov 10, 2018

View reviewed changes

jnothman reviewed Nov 12, 2018

View reviewed changes

jnothman reviewed Nov 13, 2018

View reviewed changes

thoo force-pushed the add_codeblock_copybutton branch 2 times, most recently from 6be1ca5 to 11fd009 Compare November 14, 2018 00:12

thoo added 5 commits November 13, 2018 19:26

No dependencies: added stylesheet and js files

302b5f7

retrack build_doc.sh

09b9ff2

Add comment

e504a40

flake8 error

866ae69

Change sphinx_copybutton as local sphinx_extension.

989f863

thoo force-pushed the add_codeblock_copybutton branch from 11fd009 to 989f863 Compare November 14, 2018 00:27

Move css/js file under sphinxext/_static

c7e5988

jnothman reviewed Nov 14, 2018

View reviewed changes

use relative path

d5741b9

jnothman reviewed Nov 14, 2018

View reviewed changes

Move code from sphinx_copybutton.py to __init__.py

99c2421

minor change in conf.py

2959770

thoo closed this Jul 16, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add sphinx-copybutton for codeblock #12528

Add sphinx-copybutton for codeblock #12528

thoo commented Nov 6, 2018

eamanu commented Nov 6, 2018

rth left a comment

rth Nov 6, 2018

thoo Nov 7, 2018

eamanu commented Nov 6, 2018

thoo commented Nov 7, 2018

qinhanmin2014 commented Nov 9, 2018

thoo commented Nov 9, 2018

eamanu Nov 9, 2018 •

edited

thoo Nov 9, 2018

thoo Nov 9, 2018

eamanu commented Nov 9, 2018

eamanu commented Nov 9, 2018

qinhanmin2014 left a comment

thoo commented Nov 10, 2018 •

edited

qinhanmin2014 commented Nov 10, 2018

jnothman left a comment

jnothman Nov 12, 2018

jnothman Nov 12, 2018

jnothman commented Nov 12, 2018 via email

thoo commented Nov 12, 2018

thoo commented Nov 12, 2018

jnothman Nov 13, 2018

thoo Nov 13, 2018

jnothman Nov 14, 2018

jnothman left a comment •

edited

thoo commented Nov 15, 2018

		@@ -0,0 +1,116 @@
		// Please see details at https://github.com/choldgraf/sphinx-copybutton

Add sphinx-copybutton for codeblock #12528

Add sphinx-copybutton for codeblock #12528

Conversation

thoo commented Nov 6, 2018

eamanu commented Nov 6, 2018

rth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eamanu commented Nov 6, 2018

thoo commented Nov 7, 2018

qinhanmin2014 commented Nov 9, 2018

thoo commented Nov 9, 2018

eamanu Nov 9, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eamanu commented Nov 9, 2018

eamanu commented Nov 9, 2018

qinhanmin2014 left a comment

Choose a reason for hiding this comment

thoo commented Nov 10, 2018 • edited

qinhanmin2014 commented Nov 10, 2018

jnothman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jnothman commented Nov 12, 2018 via email

thoo commented Nov 12, 2018

thoo commented Nov 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jnothman left a comment • edited

Choose a reason for hiding this comment

thoo commented Nov 15, 2018

eamanu Nov 9, 2018 •

edited

thoo commented Nov 10, 2018 •

edited

jnothman left a comment •

edited