Single document mode about jupyter-book HOT 26 CLOSED

I'm in general a fan of making things explicit rather than trying to be clever and changing behavior based on the type of input.

As a start, why not just let people explicitly pass --notebook or --report...in the future if we'd like to make the API more clever, we can do that more easily than if people start expecting cleverness and we take it away from them.

from jupyter-book.

Another thing I'd add to the requirements is that it is easy/the default to hide code cells and only hhow their output. The output area has a button to reveal the input for just that cell.

Maybe we can get away with providing one folder that is self-contained instead of having to fit everything into a single HTML file. Would probably reduce complexity a bit and make nicer HTML.

from jupyter-book.

if we can relax the "one file" requirement, this will require a good bit less re-jiggering in the jupyter book code!

So maybe an MVP here is: jupyter-book report my.ipynb and it generates a folder w/ a single, clickable HTML file in it?

from jupyter-book.

nice! yep I totally agree that's a case where we'd just like nice single-page styling, but not the whole sidebar. re: auto-expand, I'm 50/50 on it, because I kinda like choosing the "right" width for content and leaving it at that, but also open to thoughts on this!

from jupyter-book.

Should I open a different issue for that? After all, parametrized books could also be thinkable.

Go for it, I think that'd be a really interesting feature to support

So pandoc is nothing that will come in the near future?

In the very near future, probably not, but definitely something to think about in the medium-to-long term future

Should I try to enable tocbot for the single document mode?

Go for it! I actually put some of the pieces in place already.

The page function is already doing:

• Link the tocbot.js script: https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/page/page.py#L325
• Add an empty "onthispage" <nav> element to the output HTML (which is used by tocbot in the book JS to add the TOC, I just haven't gotten it working on a single page yet): https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/page/page.py#L111

So you might be able to get this working with a small bit of fiddling with JS and CSS (to place the TOC in the right location on a single page)

from jupyter-book.

-> PR #426

• Do we want the TOC at the top of the page or in a sidebar? (Ideally, that could be influenced by providing custom templates)
• It would be great to factor out the HTML generation to template files, instead of stitching it together in python.

from jupyter-book.

Thanks for starting this discussion @choldgraf !

I do think a common use case for a one-page report — and so something to keep in mind — would be including citations with a generated bibliography. It'd be great to make sure we're linking that either with citeproc in pandoc or an SSG extension like jekyll scholar.

RE: whether these things need to be linked in the HTML or just in the included folder: I'm 👍 to @betatim's point that having it in one folder will make for nicer HTML. It also fits more smoothly into Jupyter Book's current workflow, which is appealing in and of itself.

Are there any other ways in which we envision this differing from the current set up ? Where, AFAICT, we go:

• ipynb --> md (with the help of nbconvert or potentially pandoc)
• md --> html (with the help of an SSG, currently jekyll)

The biggest potential difference that I can immediately think of is that we're likely to want different default CSS for a one-page report vs a multi-page report, but that seems like something we can iterate on !

from jupyter-book.

Sounds like a good v1 to me!

How does jupyter book deal with running notebooks in the ipynb -> md step? I think for this I'd be Ok with (or prefer) that the notebook is converted as is and execution is left to a tool like nbcovnert --with-the-right-args-here or papermill.

from jupyter-book.

Very excited about the MVP idea !

One question for the arguments -- is there a reason to specify report ? If we don't have that option, what would the my.ipynb output look like ?

Right now, jupyter book executes the notebooks I believe, unless you turn that behaviour off. Could you expand a little more on what would be the reason to not execute, @betatim ?

from jupyter-book.

@betatim currently jupyter-book does not execute the notebooks, though it does provide a helper script to do it if you'd like (jupyter-book run path/to/folder I think).

re: arguments, I was just thinking that since we'd need to trigger new behavior (e.g. there will be some URL cleaning etc since we're no longer assuming that a server is serving the HTML files) that it'd make sense for Jupyter-Book to explicitly ask you to specify if you want report-like behavior or book-like behavior. WDYT?

I am working on an MVP now :-)

from jupyter-book.

🚀 amazing.

I hadn't realized we turned off that behavior when you updated to a CLI -- or maybe I'm just misremembering. Thanks for clarifying, @choldgraf !

My initial thought was that from a user-perspective we'd likely want report and not-report to look identical for a single notebook. In both cases, the UX (i.e., that users should be able to host the output on github or open it locally) would be the same, just the back-end would be different. Is that right ?

If it is, then I'm not sure why a user would need to specify the alternate behavior. Is there a way we could infer it based on whether we're passed a folder or a single notebook ?

Sorry if I'm missing another consideration, here !

from jupyter-book.

in this case, the reason is because building a book looks like:

jupyter-book create <bookname> --content-folder <path-to-content>

while the report is

jupyter-book report <path-to-ipynb>

I see what you mean though. What if, instead a different CLI for reports, we did something like:

jupyter-book create <my-report-name> --notebook <path-to-notebook>

and if notebook was passed instead of content-folder, then it'd trigger the report behavior.

from jupyter-book.

got an MVP working: https://www.dropbox.com/s/s25dhcarxgcytqf/report.gif?dl=0

only problem is that it takes a while...I think there's some unnecessary complexity in there that we could optimize out. Does the general user-facing approach seem reasonable?

from jupyter-book.

I'd merge a PR that implemented that GIF 😍.

Not executing notebooks: I was thinking for a paper/article/blog post executing the notebook could potentially take "a very long time" depending on what it was doing. Hence thinking that JB would only convert what is there. This would also allow you to turn partially executed notebooks into reports ("look this is howsdf I did it, then I left some gaps for you the reader").

I like jupyter-book create <my-report-name> --notebook <path-to-notebook> as it specifies the output folder (where the report command presumably tries to guess it?). Can we shorten it to jupyter-book create <my-report-name> <path-to-notebook>? Though you'd have to start guessing based on "is this a folder or a notebook". 🤷‍♂️

from jupyter-book.

That MVP looks amazing ! And the "sometime later" aspect is probably something we can improve across JB as a whole -- #83 might be one way.

Not executing notebooks: I was thinking for a paper/article/blog post executing the notebook could potentially take "a very long time" depending on what it was doing. Hence thinking that JB would only convert what is there.

That makes sense, @betatim, thanks !

re shortening to jupyter-book create -- this was my original idea, but I see the concern. One thought there -- if someone passed a folder with only a notebook in it and no other contents, would we expect identical behavior ? Or something different ?

from jupyter-book.

One thought there -- if someone passed a folder with only a notebook in it and no other contents, would we expect identical behavior ? Or something different ?

I think that is a good example for why we should resist guessing and go for an explicit UI.

from jupyter-book.

Just dropping in to say that this would be a really desirable feature for me! Currently using Jupyter Book for a pipeline tutorial, and the current format (i.e. sidebar with only one "link"/section) is wasting some space. My images are also a bit smaller than I'd like them; I'm wondering if the single document mode would auto-expand these since the sidebar will no longer be needed?

Live demo: https://mathieuboudreau.github.io/pipelines-jupyter-book/01/sct_mtsat

from jupyter-book.

but not the whole sidebar. re: auto-expand, I'm 50/50 on it, because I kinda like choosing the "right" width for content and leaving it at that, but also open to thoughts on this!

So currently, when I build my books, any PNG images I had loaded in my notebook are converted in the markdown file to the ![]() markdown notation for figures, e.g.:

https://github.com/mathieuboudreau/pipelines-jupyter-book/blame/be27a0a1a117abf414d0eb7a7c219143247439f4/_build/01/sct_mtsat.md#L123

I don't think there is (1) a way for me to set the image width with this markdown notation (I could manually write HTML after it's built I guess), and (2) setup my image width in the Jupyter Notebook in a certain way so that when I build the Jupyter Book it will auto-assign that width in the markdown (but maybe I'm mistaken).

What I meant was, I'm hoping that when the sidebar is removed, since the document will take more of the web page, that the markdown will "know" to use more of it and adjust itself accordingly (but maybe not from your comment?)

from jupyter-book.

Hi,

I really love this feature! Sometimes it's really useful to quickly render a single document. Also for some larger projects, the "one book" approach seems a bit unflexible to me and I prefer to break it down into multiple standalone reports.

There hasn't been any activity on this for a while. Are there any updates on this? I am happy to contribute to move this forward.

To summarize from the thread above (correct me if I'm wrong!), what currently works is:

• render a single html page from a single notebook (jupyter-book page)
• hide input/outputs

The following features are missing:

• embedding images in a single file
• table of contents

Additionally, I would find it very useful to be able to parametrize reports (as in rmarkdown).

Suggestions

• the TOC + embedding images in a self-contained file would be 'for-free' if jupyter-book switched to pandoc for conversion (#94).
• For parametrized reports, we could probably integrate/copy from papermill here.

Let me know what you think and how you'd like to move forward!

Cheers, Gregor

CC @mwouts

from jupyter-book.

Thanks for the input! A few quick thoughts:

• I think that embedding images should work with jupyter-book page...if not then IMO that's a bug :-)
• Adding a TOC should also be fairly straightforward. Right now we're actually using tocbot to add a table of contents, and it shouldn't be too hard to get this working on a single page
• For parameterized reports, can you give an idea for what kind of API you had in mind? (e.g. jupyter-book page myreport.ipynb --execute --params key1=value1 key2=value2?)
• There's definitely the potential for Pandoc in the future, though I wouldn't say it comes for free - it'd require us adding a new non-trivial dependency and re-working a ton of the CSS and javascript rules, it'd also probably slow down the build process. But I am definitely open to the idea!

from jupyter-book.

For parameterized reports, can you give an idea for what kind of API you had in mind? (e.g. jupyter-book page myreport.ipynb --execute --params key1=value1 key2=value2?)

Pretty much that. Probably quoted, that should be easier to handle by an argument parser?

jupyter-book page myreport.ipynb --execute --params="key1=value1 key2=value2"

Should I open a different issue for that? After all, parametrized books could also be thinkable.

There's definitely the potential for Pandoc in the future, though I wouldn't say it comes for free

Oh, I don't believe pandoc is for free. Rather, if we had switched to pandoc, then adding the TOC would be very straightforward. (But as you pointed out, it shouldn't be a big deal anyway).

So pandoc is nothing that will come in the near future? Should I try to enable tocbot for the single document mode?

from jupyter-book.

Closing as this should be superceded by beta.jupyterbook.org and now exists with jupyter-book page

from jupyter-book.

Seems the page command no longer exists.
Was this feature deprecated?
Or moved onto another command?

from jupyter-book.

Nevermind!
Found it in the changelog:

Seems like passing a single file to jupyter-book build is the new way of achieveing this.

from jupyter-book.

@paw-lu How did you specify a single file? i am looking to output a single HTML file as well

from jupyter-book.

@paw-lu How did you specify a single file? i am looking to output a single HTML file as well

Simply by passing a single file to jupyter-book build

like this:

% jupyter-book build single_file_notebook.ipynb

This will take a single file as an input, but will not give you a single standalone HTML file as an output.

There's some discussion on #1399 on that. But AFAIK it's not currently possible.

from jupyter-book.