Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Fixed html doc usage docs to fix 6.x #1386

Merged
merged 4 commits into from
Sep 13, 2020
Merged

Fixed html doc usage docs to fix 6.x #1386

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2fee22e
Fixed html doc usage docs to fix 6.x
MSeal Sep 13, 2020
b429b10
Apply suggestions from code review
MSeal Sep 13, 2020
7f858c5
Doc fix for build
MSeal Sep 13, 2020
f0ee233
Actual fix for docs
MSeal Sep 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/source/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ Changes in nbconvert
6.0.2
-----

A patch for a few minor issues raised out of the 6.0 release.

Comprehensive notes
~~~~~~~~~~~~~~~~~~~

Fixing Problems
+++++++++++++++
- Added windows work-around fix in CLI for async applications :ghpull:`1383`:
Expand All @@ -23,8 +28,8 @@ Testing, Docs, and Builds

A quick patch to fix an issue with get_exporter :ghpull:`1367`:

6.0.0
-----
6.0
---

The following authors and reviewers contributed the changes for this release -- Thanks you all!

Expand Down Expand Up @@ -69,9 +74,8 @@ The following authors and reviewers contributed the changes for this release --
* Tyler Makaro
* Yu-Cheng (Henry) Huang


Significant changes
~~~~~~~~~~~~~~~~~~~~
Significant Changes
~~~~~~~~~~~~~~~~~~~

Nbconvert 6.0 is a major release of nbconvert which includes many significant changes.

Expand Down
13 changes: 8 additions & 5 deletions docs/source/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,18 @@ HTML
~~~~
* ``--to html``

- ``--template full`` (default)
HTML Export. Note on backward compatibility: Be aware that if you were using custom copies of the old 5.x
template files (i.e. ``--template``), you will now need to use ``--template-file path/to/old/file.tpl``
in order to use that file in compatibility mode as opposed to other options.

- ``--template lab`` (default)

A full static HTML render of the notebook.
This looks very similar to the interactive view.
This looks very similar to the jupyter lab interactive view.

- ``--template basic``
- ``--template classic``

Simplified HTML, useful for embedding in webpages, blogs, etc.
This excludes HTML headers.
Simplified HTML, using the classic jupyter look and feel.
Copy link

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/)

Copy link
Contributor Author

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.

Copy link

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).

Copy link
Contributor Author

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.

Copy link

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.

Copy link
Contributor Author

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.


.. _convert_latex:

Expand Down