Reports with Jupyter Book

[lwasser]

Hey there @choldgraf et al... i'm following up on this thread... i may have missed this in the docs. if i want to generate a single page report (my students do this)... with jupyter notebook - can jupyter book do this without all of the overhead of the book / yaml files etc etc?

https://discourse.jupyter.org/t/generating-reports-for-jupyter-notebooks/279/18

all i want to do is create a notebook, hide cells - add citations (yay!) and then export to html or pdf.
is this possible now and if so can you kindly direct me to the docs as i can't seem to find it but swear i saw it someowhere at some point.

Thank you!! so excited to use this in my class if it's possible!!

[choldgraf]

Could you try this: https://jupyterbook.org/start/build.html?highlight=jupyter%20book%20page#build-a-standalone-page

?

The API there might change a little bit (@AakashGfude is working towards this) but the general approach should be there. That work?

[lwasser]

@choldgraf ok... this is the start of my dream of having reproducible reports as outputs for my class coming true!! YAY. i have to wrap my head around a few core differences with this vs rmarkdown BUT in the meantime... a few questions if you don't mind. and please know i see this has come a LONG way - and i'll totally try it out in my class this spring and can give you feedback if you'd like! i'll also make online lessons to support using it for reports. So my questions are not intended to call out anything "wrong" ... just trying to understand the direction that this is going.
OK on to questions...

1. i just created a lovely little report and was able to "hide" the code but not remove it. that's neat!
   Question: the output is a set files and such vs a single html document. For sharing - would someone have to zip up the entire _build directory? I'm just curious as the output dir name _build is generic which makes it hard for someone opening it to figure out where the html file is to look at and neither file actually contains the report name (the notebook name). So imagine the use case - i create a nice report full of technical stuff but i want to share it with a less technical user. emailing an html file is simple. emailing an entire directory that will unpack with the name _build may be a bit confusing and require instructions. i'm just checking that - that is how it works right now? The nice thing about this might be if it exports images as files. i haven't tried to create a plot yet but that could be very useful. This is more a usability question related to sharing outputs.

question 2 -- the footer -- it's cool and i get why you have it but is there a way to turn that off or adjust it in the case of a student report? i know why you have it and want to support the project but may not want that footer on a report that is published for instance. this is a minor ask.

question 3 - last but not least -- do you envision the ability to add custom css templates in the future - this is absolutely and won't serve a large body of users but i just wondered.

i'll spend a bit more time playing around with citations and such because that is also what we need for student reports AND using GLUE!! yes! THANK YOU SO MUCH.

i've asked this each year since i started teaching in python and now... i think is the time to use this tool in my class!
NOTE: our rmarkdown report lessons are often the most popular ones on our site. i could see a lesson on jupyter book being equally popular too!!

[lwasser]

also i didn't know github supported questions like this!! amazing!

[lwasser]

ok me again -- i'm playing with it a bit more

1. the belab link is at the top of my html file when i create it however i don't expect that to work. Can i disable that feature.
2. when i print a pdf - it's not quite a report like pdf. it's more like an version of the web page in pdf form.

i'm just curious if this is all expected behavior OR if it's possible to just remove those icons at the top and the side bar and make it more of a full screen pdf with the content in it?

[choldgraf]

this is all awesome feedback - I think that we are not quite where you want to be with "reports", but I bet that this would be in-scope for new development etc. I wanna ping @chrisjsewell @mmcky and @AakashGfude to see what they think about some of the ideas in here. I agree with you that the "single-page" use-case is perhaps a bit different from the "full book" use-case, and perhaps we want some special cases in there. It would be great to structure this feedback into a kind of roadmap towards improving "reports" in jupyter book

[mmcky]

this is all great feedback. I would very much like to see reports on the roadmap as it would be super useful to have a tool that could quickly build beautiful reports / project proposals etc. with relative ease. While the current focus is to build books (and not support every possible feature on purpose to simplify writing books / projects) -- i'd love to see on the roadmap support for different end use domains such as reports.

the footer -- it's cool and i get why you have it but is there a way to turn that off or adjust it

to cater to different end-use domains we will need to think hard about how to have control over various document components (such as footers / headers) without overcomplicating setup. I think the focus will be make book writing straight forward -- other domains may need a bit more config. I find this a nice resource when thinking about document structures (it based on LaTeX) with articles, book etc. It would be great to have a system that could cater (to some degree) to the scope that LaTeX offers.

do you envision the ability to add custom css templates in the future

We have a few themes in the medium term pipeline at the moment (light, dark etc.). custom themes is something that should be possible -- but will require some good documentation to make this accessible. A good idea to add to a roadmap

[lwasser]

hi there @choldgraf @mmcky this is great. Thank you. IF you develop the single page report further (which would be incredibly awesome and i can tell you MANY PEOPLE would use it) ... i'd LOVE to be involved for testing and feedback (IF and only if THAT IS HELPFUL). I'll also have a lot of feedback from my students if i use it in the spring so i can happily colate that for you IF that is useful.

again this has already come a long way!! It would be really cool to be able to refine and clean up a singe page document.

[choldgraf]

@lwasser maybe a nice first step would be to make a "wish list" for relatively minor changes to the current "single-page" mode, and we can see which are low-hanging fruit that are in-scope and relatively easy to fix up - we can create issues for those and hopefully someone in the community can get to implementing fixes!

[lwasser]

@choldgraf that sounds great. i can do that tomorrow. i'll prioritize the wish list as well and will try to think about the most common use cases vs things i may just appreciate that may be less used (for instance how many people will modify css - not many... BUT the community may make add on templates in the future if this were an easy option). i'll think about this a bit more and will make a list! that sounds perfect. THANK YOU for the opportunity to provide input!!