Rename this to nbauthor?

[choldgraf]

I just had a thought - perhaps this repository could be an experiment in offloading as much of the authoring tools as possible onto the notebook metadata (as opposed to requiring a markdown flavor that supports references etc...I think that'll happen at some point but who knows when).

For example, one could imagining parsing the notebook cell metadata for a references field. You could collect all the references in a unique list, as well as a set of pointers for which cells contained those references, then auto-generated a bibliography at the bottom with some nice HTML to the side of the rendered cell.

Perhaps this tool could be nbauthor, and a bit more expansive than just generating a report.

@betatim @lawasser any thoughts on that? Is this an issue worth pushing a bit further?

[lwasser]

It's so awesome you are exploring this !! funny enough @choldgraf i did a quick search today and found this nbreport tool on pypi by accident. So it might not be a bad idea to reconsider the name it you want it on pip eventually. :)

my apologies. I don't fully understand what you mean by offloading authoring tools into the metadata. BUT i can tell you that rmarkdown supports references too. The way they handle refs is in the markdown text however combined with bib info in the first "cell" of the markdown file via a yaml list. So when the file is parsed, it looks at the yaml, gets the bib tex list of references and connects those references with what is cited in the markdown inline. All this requires then is a yaml cell at the top to define stuff (for references).

So without knowing quite enough. i think that it would be wonderful to see some structure that would make is easy and standard to add on to the potential for authoring tools. ie someone might mirror the refs in rmarkdown for jupyter . I could see that structure being something at the top of the notebook where you could define stuff that everyone used. so this would come from jupyter. It could accept css, refs or whatever peopel envision.Or maybe the top cell has a toolbar that allows you to easily build out metadata in json format? Then yes some sort of way to access the metadata to build out functionality as needed on top of some basic report authoring tools like

1. hiding code / hiding outputs
2. making the notebook prettier (ie add css file to the yaml and author a pretty output)
3. captions (which someone could build something around caption refs). this is done in R etc

And make it all easy to do rather than having to dig into the metadata itself. This might be what you're suggesting above already! and i hope i'm not too off track here! just my thoughts. this is so so cool.

[choldgraf]

FWIW, this tool already does numbers 1 and 3. It doesn't yet allow for 2 but that should be easy. The main question there is how you let people specify a CSS file. It's easy enough if you're doing it from the command-line but what about from the UI (e.g. do you look for a "css_file" metadata, do you use an environment variable, etc)

[lwasser]

got it! So i think the discussion of adding a css file aligns with references, etc.

options maybe?

1. yaml in the first cell (like we did with my lessons) it's treated as "Raw nbconvert" and you / jupyter/ the community begin to define a yaml structure for things like css that everyone can build on top of. you could use the rmarkdown approach as a template.

   ---
   title: "My Report"
   author: "First Lastname"
   output:
   html_document:
   toc: true
   number_sections: true
   theme: united
   highlight: tango
   ---

   or

   ---
   title: "My Report"
   output:
   html_document:
   css: styles.css
   refs: bib.tex
   ---

2. You devise some clever interface that allows people to add stuff to the backend json but that is visible on the front end via a toolbar and interface or something? that might be too much work and complexity and could be done later.

You and @betatim might have some clever ideas. @mbjoseph might have some ideas too! i'll keep thinking about it but it needs to be simple but with a structure that people can do other things with. (as you have already suggested) :) In the above you can see how they build out more complex documents using various yaml items. so we just need space for that to happen.

NOTE that R has lots of templates that the community developed using css once this fairly simple structure was available. :) i can see this exploding with jupyter too!

[lwasser]

docs in case this is of interest. i know this is Jupyter but just so you can see. here

[choldgraf]

one question: could you use RMarkdown for writing python code? Is it only for R?

If no, then couldn't we just generate an RMarkdown file from the jupyter notebook, then run RMarkdown on it to generate HTML?

[mbjoseph]

R Markdown can be used with python for sure. With the reticulate package you can even use conda and virtualenv: https://cran.r-project.org/web/packages/reticulate/vignettes/r_markdown.html

[choldgraf]

Just pushed an edit to this repo that lets you give a custom CSS rule. You can either call this from the command line with nbreport --css path/to/file.css or if a notebook has css_extra: 'path/to/file.css' then the button download will work too

[lwasser]

oh R markdown does support other kernels including bash. Here has been the sticking point for me (and i think it's been a while since i've tried so it could be better). I was never able to get R markdown to find the right python kernel. R markdown needs to run the code and build the outputs. So it's not like jupyter where you can export a notebook as is OR run it then export. this could be a good time to poll the community on this too. For me in a class for instance i need things to work consistently and using several tools is challenging. BUT rmarkdown has a TON of authoring flexibility built into it. it's awesome!

if you went this route would you be able to add this setup to a jupyter hub / binder config?

[lwasser]

@mbjoseph have you actually gotten rmd to easily find different environments? Like i said i haven't tried in a while. maybe a year or more even!! last time i tried i spent forever trying to get it to find my ea-python kernel.

[lwasser]

Is this -- css_extra: 'path/to/file.css'

Metadata in the first cell @choldgraf ? I’m going to play with this but maybe not till tomorrow or later. So very excited to have this for notebooks.

[choldgraf]

it's in the metadata for the notebook itself (each notebook has a top-level metadata section, and each cell also has its own metadata section)

[choldgraf]

also pinging @emdupre who was also interested in a single-page report-generation tool.

[mbjoseph]

@lwasser yes - I put together a little example that uses our earthpy-dev conda environment and plots the Rocky Mountain National Park RGB GeoTIFF using the earthpy.spatial.plot_rgb function: https://gist.github.com/mbjoseph/4f0269d741bec91977bfb0efc6eaf6c8

Works like a charm locally, but curious to know whether it works for you too (assuming that the reticulate package is installed, along with our earthpy-dev conda env).

R Markdown support has matured considerably in the past year, so it's possible that it is easier now to use than when you last tried!