-
Notifications
You must be signed in to change notification settings - Fork 567
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fixed html doc usage docs to fix 6.x #1386
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some small changes for clarity. Thanks @MSeal
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
|
||
Simplified HTML, useful for embedding in webpages, blogs, etc. | ||
This excludes HTML headers. | ||
Simplified HTML, using the classic jupyter look and feel. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it might be useful to also document the “embeddable” version, which would be --template-file=classic/base.html.j2
(or lab/
)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
--template=classic
is preferred over --template-file=classic/base.html.j2
. It's possible in a future release that when the backwards compatibility is removed that the second pattern might not work that way anymore (--template=classic --template-file=notbase.html.j2
might be required in some distance release, or no support template-file at all). https://nbconvert.readthedocs.io/en/6.0.2/changelog.html?highlight=--template-file#id3 outlines how to use template-file to refer to a specific .tpl
5.x file.
I'm hesitant to promote it more elsewhere for other uses because some of these always-supported patterns made the 6.0 upgrade harder. But I could be convinced it's a good idea to document it more if people feel strongly about it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
--template=classic
is not a replacement for basic
/classic/base.html.j2
, because it produces a full 13k line (?!) HTML document with styles and JS. This is not usable for embedding, at least not without using a HTML parser to get rid of the 13k lines of <head>
. classic/base.html.j2
produces just the notebook code and expects styles to be added in elsewhere (and we do it that way in Nikola).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm you're correct. I wasn't as involved with the html template changes from 5.x to 6.x. It looks like adding --template-file=base.html.j2
along with --template=classic
gets you back to close to the original --template=base
pattern without all the styles and JS. Can you try that and see if it matches expectations? I can discuss with the other maintainers how to better preserve that capability in a clearer format with the new system if so.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems to work, both from the command line and code. It would be good to have an officially recommended way to do this in the docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree. Thanks for raising the concern and documentation gap. I'll talk with the other maintainers and see if we want to introduce an easier way to run this combination before I document it, but I don't believe we'll remove the pattern that worked for you here.
Partially resolves #1384