A better ipynb->html template
BoPeng opened this issue · 11 comments
sos convert my.ipynb my.html
is essentially calling
jupyter nbconvert
with a default template that
-
Use pygments to generate static syntax hilighting. It serves its purpose but does not show language-specific highlighting or interpolated texts (effect of
expand=True). It does not show language selector box either. -
No TOC, which seems to be useful to have in most cases.
Given that we already have templates for our online documentation that uses codemirror and has a toc, perhaps we should provide a better default template....
All templates have been re-written ... now we need a TOC template.
Cool -- is this page now on the new template? I noticed there seems unwanted space at the end of some of the long code cells.
I have not figured out this problem yet. The extra space is added as a min-height of the input cell so that when the cells are rendered by codemirror, the actual cell height would not change and "shake" the page. However, it has been difficult to estimate this height from number of rows so the min height can be too big for long code.
Still working on it though.
Page updated. Should be better but might shake slightly.... will see.
For TOC, need to work with http://gregfranko.com/jquery.tocify.js/.
It looks nice! I was not sure if I can see the shake, though.
The new TOC looks a lot cooler! But seems tricky to get it work with the search bar, right?
Three templates are added:
sos convert my.ipynb my.html --template sos-full-toc
sos convert my.ipynb my.html --template sos-report-toc
sos convert my.ipynb my.html --template sos-cm-toc
TOCs added to examples: https://vatlab.github.io/sos-docs/doc/examples/RNASeqDE.html
Great. Is the level of displayed TOC controlled by one of the template options? The example tocify page can display, when clicked on, more detailed level of headers. Wondering if that's controlled by some options.
I just used all default options of tocify. You can explore the options and adjust css and test them by pointing directly to the template file (e.g. --template src/sos_notebook/templates/sos-full-toc.tpl). One thing I would like to have is perhaps a "header" that goes to the top of the page.
I am reopening this ticket, because I received a (workflowr) report from my colleague, which is a enjoyable read.
https://willwerscheid.github.io/MASHvFLASH/MASHvFLASHnn2.html
I think what has helped the most is the Code bottom that allows me to expand the part am interested in. Our current format that expands all code is a bit hard to use in practice. I in fact find it tedious to have to set what to output for each cell (report "tag"s) and not convenient to always have to go to the top of the page to click for codes to show up.
I believe workflowr simply uses bootstrap templates. Is it something we can adopt?
The report series of templates aims at reports that completely hides the details (see also #123). They are supposed to show only results, with code to check the details if needed. The cm series of templates aims at showing the code and results in a notebook format. What you just showed kinds of sitting in the middle and can certainly be supported with some other templates. @HenryLeongStat might be interested in checking the details.
Seems interesting! Will take a look at it on weekend!