@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.
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!).
@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?
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!
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:
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
curl tabs copy-to-clipboard-enabled!
Keep us posted!
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!
Does look more like what you wanted?
Therefore, when you click Copy to clipboard it will copy:
Therefore, when you click the Copy to clipboard button it will copy:
qiime metadata tabulate
qiime deblur visualize-stats
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:
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!
@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!
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!