-
Notifications
You must be signed in to change notification settings - Fork 805
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
toc2: sidebar + html export #593
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
a0f2504
toc2: sidebar + html export
jfbercher a6ad455
toc2: sidebar - change reading of initial config
jfbercher db5222e
toc2: sidebar - update extension loading
jfbercher 98a2c70
toc2: added toc3 template for demo purposes
jfbercher 9d1afc8
toc2: fixes to sidebar + navigation menu
jfbercher 2877377
Updated README
jfbercher 9c6720b
Updated description in .yaml
jfbercher File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
"""Toc2 Exporter class""" | ||
|
||
#----------------------------------------------------------------------------- | ||
# Copyright (c) 2016, the IPython IPython-Contrib Development Team. | ||
# | ||
# Distributed under the terms of the Modified BSD License. | ||
# | ||
#----------------------------------------------------------------------------- | ||
|
||
#----------------------------------------------------------------------------- | ||
# Imports | ||
#----------------------------------------------------------------------------- | ||
|
||
from traitlets.config import Config | ||
from traitlets.config import Config | ||
from nbconvert.exporters.html import HTMLExporter | ||
|
||
#----------------------------------------------------------------------------- | ||
# Classes | ||
#----------------------------------------------------------------------------- | ||
|
||
class TocExporter(HTMLExporter): | ||
""" | ||
Exports to an html document, embedding toc2 extension (.html) | ||
""" | ||
|
||
def _file_extension_default(self): | ||
return '.html' | ||
|
||
def _template_file_default(self): | ||
return 'toc3' | ||
|
||
output_mimetype = 'text/html' | ||
|
||
def _raw_mimetypes_default(self): | ||
return ['text/markdown', 'text/html', ''] | ||
|
||
@property | ||
def default_config(self): | ||
import jupyter_core.paths | ||
import os | ||
c = Config({'ExtractOutputPreprocessor':{'enabled':True}}) | ||
c.merge(super(TocExporter,self).default_config) | ||
|
||
user_templates = os.path.join(jupyter_core.paths.jupyter_data_dir(), 'templates') | ||
c.TemplateExporter.template_path = [ | ||
'.', user_templates ] | ||
return c |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,11 +2,15 @@ | |
|
||
## Description and main features | ||
|
||
This extension adds a small button in the main toolbar, which enables to collect all running headers in the notebook and display them in a floating window. | ||
The toc2 extension enables to collect all running headers and display them in a floating window, as a sidebar or with a navigation menu. The extension is also draggable, resizable, collapsable, dockable and features automatic numerotation with unique links ids, and an optional toc cell. Finally, the toc can preserved when exporting to html. | ||
|
||
![](icon.png) | ||
#### First demo: | ||
![](demo.gif) | ||
|
||
The table of contents is automatically updated when modifications occur in the notebook. The toc window can be moved and resized, the table of contents can be collapsed or the window can be completely hidden. The position, dimensions, and states (that is 'collapsed' and 'hidden' states) are remembered (actually stored in the notebook's metadata) and restored on the next session. The floating window also provides two links in its header for further functionalities: | ||
#### Second demo: | ||
![](demo2.gif) | ||
|
||
The table of contents is automatically updated when modifications occur in the notebook. The toc window can be moved and resized. It can be docked as a sidebar or dragged from the sidebar into a floating window. The table of contents can be collapsed or the window can be completely hidden. The navigation menu can be enabled/disabled via the nbextensions configuration utility. It can also be resized. The position, dimensions, and states (that is 'collapsed' and 'hidden' states) are remembered (actually stored in the notebook's metadata) and restored on the next session. The toc window also provides two links in its header for further functionalities: | ||
|
||
- the "n" link toggles automatic numerotation of all header lines | ||
- the "t" link toggles a toc cell in the notebook, which contains the actual table of contents, possibly with the numerotation of the different sections. | ||
|
@@ -16,11 +20,30 @@ The state of these two toggles is memorized and restored on reload. | |
![](image.png) | ||
|
||
## Configuration | ||
The initial configuration can be given using the IPython-contrib nbextensions facility. The maximum depth of headers to display on toc can be precised there (with a default of 4), as well as the state of the toc cell (default: false, ie not present) and the numbering of headers (true by default). The differents states and position of the floating window have reasonable defaults and can be modfied per notebook). | ||
|
||
|
||
The initial configuration can be given using the IPython-contrib nbextensions facility. It includes: | ||
|
||
- The toc initial mode (floating or sidebar) | ||
- The maximum depth of headers to display on toc (with a default of 6) | ||
- The state of the toc cell (default: false, ie not present) | ||
- The numbering of headers (true by default). | ||
|
||
The differents states and position of the floating window have reasonable defaults and can be modfied per notebook). | ||
|
||
## Export | ||
It is possible to export (most of) table of contents functionalities to html. The idea is to link a relevant part of the javascript | ||
extension and the css, and add a small script in the html file. This is done using a template by | ||
``` | ||
jupyter nbconvert FILE.ipynb --template toc | ||
``` | ||
or | ||
``` | ||
jupyter nbconvert FILE.ipynb --template toc2 | ||
``` | ||
For the first template (toc), the files toc2.js and main.css (originally located in JUPYTER_DATA_DIR/nbextensions/usability/toc2) must reside in the same directory as intended for the html file. In the second template, these files are linked to the IPython-notebook-extensions github website. Export configuration (parameters) shall be edited directly in the template files (in templates directory JUPYTER_DATA_DIR/templates). An option "Save as HTML (with toc)" is also provided in the File menu and enable to directly convert the actual notebook. This option requires the IPython kernel and is not present with other kernels. | ||
|
||
|
||
# Testing | ||
- At loading of the notebook, configuration and initial rendering of the table of contents were fired on the event "notebook_loaded.Notebook". Curiously, it happened that this event was either not always fired or detected. Thus I rely here on a combination of "notebook_loaded.Notebook" and "kernel_ready.Kernel" instead. | ||
- At loading of the notebook, configuration and initial rendering of the table of contents were fired on the event "notebook_loaded.Notebook". It happens that the extension is sometimes loaded *after* this event. I now rely on a direct rendering at load and on a combination of "notebook_loaded.Notebook" and "kernel_ready.Kernel". | ||
|
||
- This extension also includes a quick workaround as described in https://github.com/ipython-contrib/IPython-notebook-extensions/issues/429 | ||
|
||
|
@@ -33,6 +56,8 @@ from https://gist.github.com/magican/5574556 | |
- @JanSchulz, enable maths in headers links | ||
- @jfbercher december 06, 2015 -- Big update: automatic numbering, toc cell, window dragging, configuration parameters | ||
- @jfbercher december 24, 2015 -- nested numbering in toc-window, following the fix by [@paulovn](https://github.com/minrk/ipython_extensions/pull/53) in @minrk's repo. December 30-31, updated config in toc2.yaml to enable choosing the initial visible state of toc_window via a checkbox ; and now resizable. | ||
- @slonik-az february 13, 2016. rewritten toc numberings (more robust version), fixed problems with skipped heading levels, some code cleanup | ||
- @slonik-az february 13, 2016. Rewritten toc numberings (more robust version), fixed problems with skipped heading levels, some code cleanup | ||
- @jfbercher february 21, 2016. Fixed some issues when resizing the toc window. Now avoid overflows, clip the text and add a scrollbar. | ||
- @jfbercher february 22, 2016. Add current toc number to headings anchors. This enable to get unique anchors for recurring headings with the same text. An anchor with the original ID is still created and can be used (but toc uses the new ones!). It is also possible to directly add an html anchor within the heading text. This is taken into account when building toc links (see comments in code). | ||
- @jfbercher april 29, 2016. Triggered by @cqcn1991, cf [discussion here](https://github.com/ipython-contrib/IPython-notebook-extensions/issues/532), add a sidebar option. The floating toc window can be dragged and docked as a left sidebar. The sidebar can be dragged out as a floating window. These different states are stored and restored when reloading the notebook. Add html export capability via templates toc.tpl and toc2.tpl (see above). | ||
- - @jfbercher may 04, 2016. Added a "Save as HTML with toc" menu. Added a new "Navigate" menu with presents the contents of the toc. Changed default styling for links in tocs. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This results in two dots... There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Will correct this at next iteration. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
Would there be a way to simply include these files in the template/final output? static one page files are best for sending this stuff to my adviser :-)
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.
@JanSchulz You just have to replace the link in the template by
This assumes that the file is in the same directory as the notebook (full paths do not work in jinja tempates).
I do not do it because anyway you still need an internet connection to get access to jquery. Please make a PR with an extra template if you want
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.
IMO the default should be to include stuff which is not on a CDN, so that sending the html file will work as long as a user has access to the internet... IMO the "toc must be on my drive" is useless because IMO html exports are to be exchanged with peers and so not on my drive. Or do I misunderstand anything here?
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.
Perhaps. You do not need to have toc or the notebook installed. Everything will work as long as the user has an internet access.
If you do not have access to internet, you will not have jquery and the toc javascript will not work. This is not true in the notebook since it has a copy of jquery inside. Otherwise you need to have an access to jquery, and most of the time this suppose an internet access.
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.
+1