@thermokarst I have been reading up on rst and from what I understand there are custom “command-block” and “download” directives that you guys created as sphinx extensions. The download block uses the download.html template to render how it will look in HTML. The CommandBlockDirective(docutils.parsers.rst.Directive) class in the extension.py file handles both the command-block and download directives. However, it does not look like the “command-block” is associated with a specific jinja2 template. Is this accurate? If so, what determines how it gets rendered? If this is completely off, feel free to correct me on any of this.
Hi @patthehat033!
Yep! 
This question might be best answered by deferring to the sphinx docs for Developing an Extension. Maybe your next step could be reading up on that, then follow up here with any additional questions! Sorry, that is a bit of a cop out, but this is actually a pretty big topic, so if you aren't up to speed on that process (of developing a custom extension), it can be a bit much to wrap your head around (I know that is the case for me, personally!).
For the casual observer, this conversation is related to development of a new feature related to the user docs, @patthehat033 is working on implementing this now. Thanks! 
1 Like
@thermokarst Thanks for the reference. I did some reading on that and from what I understand the _get_literal_block_node(self, commands) function within the CommandBlockDirective(docutils.parsers.rst.Directive) class is handling the commands and pushing the content of the command-block aka the commands into a literal-block node and using ‘shell’ to highlight the node because it is a set of shell commands. Does this sound accurate?
1 Like
Yep! That sounds accurate to me! Looking ahead, I think you will ultimately need to use some kind of Javascript library to handle the mechanics of copy-to-clipboard — if that is the case, you might be able to get away with just using a CSS selector to grab the HTML elements on the page that have commands in them. This could be a bit easier when compared to manipulating the actual document nodes python-side, because you can rely on Sphinx having already rendered out the HTML document. This project (clipboard.js) looks pretty straightforward, and they already have an example of hydrating a handful of copy-to-clipboard blocks using a CSS selector that returns a list of elements. Just some food for thought, now that you have wrapped your head around the mechanics behind how Sphinx handles making HTML from RST! Keep us posted! 
@thermokarst I agree this seems like a good approach! Would you guys be okay with me using JavaScript to create the HTML buttons that will be used for the “copy to clipboard”. As well as using JavaScript to add in any ID’s and such? Otherwise, as you mentioned, I think you would have to do this on the Python side or using rst.
I will leave the decision in your hands, whatever you think makes sense! You might need to do some kind of combination of Sphinx alterations in tandem with some JS — dive in and see what happens!
@thermokarst I am testing a method that I want to run by you since it is sort of unique. Basically in the command-block you would write a comment in the command that says “#copy-to-clipboard” where you want the button placed. Then JavaScript will replace this comment with the copy to clipboard button and it will associate the button with the command before the “#copy-to-clipboard” comment. After doing some looking through the HTML it is rather challenging to add a copy-to-clipboard without coding something specific for each command block since all the commands are written slightly differently (and this generates different HTML elements). The method I suggested makes it easy for the developer to easily add a button by just adding a comment in the command and also determine where the button will be placed. This method would work for the command-block directives (I believe, I haven’t fully tested this yet, I have only tested the placement of the buttons and they look good), but I am not sure about the download directives, I would have to do that slightly different since those use the download.html template.
Any thoughts? If this is too unconventional or will not work because of the way the commands run, I will start looking into a different method.
This may be easier to understand from a visual:
Before:
After:
Thanks for the example @patthehat033 --- I think that might be quite cumbersome for both the documentation writers, as well as users taking advantage of a Copy-to-Clipboard feature. I think having one button per command-block makes sense, since we organize those blocks as "related" chunks of code/command. I think you can probably get away with coming up with a scheme to automatically add that into any non-download command-block without the document writer needing to do anything, although there probably should be a directive argument to allow the writer to disable the addition of a copy-to-clipboard button on any given command-block. As I mention above, you don't need to worry about the download variant of the command-block for now, although we probably will want to make the wget and curl tabs copy-to-clipboard-enabled!
Keep us posted!
PS -
I'm not sure I follow you here - can you provide an example of this? Thanks!
@thermokarst Thank you for the response. Originally, I figured you wanted a copy to clipboard button for each command (since there can be multiple per block). I will re-work that to meet those requirements!
1 Like
Does look more like what you wanted?
Therefore, when you click Copy to clipboard it will copy:
mkdir qiime2-moving-pictures-tutorial
cd qiime2-moving-pictures-tutorial
Therefore, when you click the Copy to clipboard button it will copy:
qiime metadata tabulate
--m-input-file demux-filter-stats.qza
--o-visualization demux-filter-stats.qzv
qiime deblur visualize-stats
--i-deblur-stats deblur-stats.qza
--o-visualization deblur-stats.qzv
Even though there are multiple commands on both of these examples.
I think this looks pretty good - maybe the button could be moved to the top row? Maybe with some CSS styling it could even be in the upper-right corner. Also, what about using a copy glyph, and using the phrase "copy to clipboard" as the alt text (on mouseover, for example). Here is an example of a copy glyph, pulled from bootstrap's subset of glyphicons, which I think are bundled in the docs right now:
glyphicon glyphicon-copy
I am curious to hear what @jairideout thinks. Thanks @patthehat033!
for placement in the upper-right corner using a copy glyph.
Thanks @patthehat033 for working on this!
@jairideout Sounds good to me! @thermokarst So it looks like the glyphicons are pulled from a fonts folder. I know you had mentioned the glyphicons might be bundled in the docs but I do not see a fonts folder. Is this something I will need to add to my project or is there a fonts folder I am missing? I tested the glyphicon and it does not seem to be showing up correctly.
Hey @patthehat033, looks like a I was mistaken. You will need to download and add the glyphicons to the _static resources in the docs repo. I don’t think you will need to amend the template for the docs, but wanted to link to that in case you do. The Bootstrap docs should help get you moving in the right direction (we are using version 3 of Bootstrap in the Q2 docs). Keep us posted!
@thermokarst Thank you for the information!
I added in the fonts folder. I also had to put the bootstrap.css file in a css folder otherwise the fonts folder would not be recognized since the bootstrap.min.css file is looking for …/fonts (I might be able to change this by modifying the bootstrap.css file but I haven’t actually tested that yet).
This seems to work for Chrome but it does not seem to work for Firefox. When I load the webpage on FireFox I get a “downloadable font: download failed (font-family: “Glyphicons Halflings” style:normal weight:normal stretch:normal src index:1): bad URI or cross-site access not allowed source: file:///home/qiime2/Desktop/docs/build/preview/_static/fonts/glyphicons-halflings-regular.woff2 bootstrap.min.css:5:3022”
Maybe it is something cross domain related like the error says - I am going to continue researching this - unless you guys have ran into this before.
@thermokarst I changed the setting security.fileuri.strict_origin_policy to false on Firefox which apparently gives the webpage access to the entire file system and that fixed the issue. So I believe it is a cross-domain issue caused by running this on my localhost, which probably will not be an issue when we put the code on an actual server. What do you guys think?
Hey @patthehat033 — it doesn’t look like you are running an HTTP server, because your error above references a file:// protocol — this is likely why you are observing that error. If you fire up a server in the built docs directory, does that fix the issue for you? After you run make preview to build the docs there is a handy one-liner that it spits out for spinning up a testing server, I will duplicate it here:
cd build/preview && python -m http.server ; cd -
If you run that, you can point your browser to 127.0.0.1:8000 to view a local copy of the built docs. Let us know how it goes!
PS - it sounds like you might be ready to think about cutting a pull request — once you are we can move some of this discussion there, which will allow us to comment on specific lines of code, etc. No rush, take your time and do what is comfortable for you. Thanks!
1 Like
@thermokarst That worked well! Totally overlooked that nice little hint at the end of the make preview command output. Will most likely have a pull request ready next week!
1 Like
Have the functionality and looks about where I want it, need to look over the code though. I am on spring break next week, but should be able to put in the pull request the week after!