Jupyter-book: Disappearing None

[matthew-brett]

Sorry for this one, but I noticed that syntax-highlighted Python 'None' is invisible in the default theme:

https://matthew-brett.github.io/dsfe/chapters/07/none

I know this question is lazy - but what is the best way to configure to avoid this? Can it be done per-page?

[choldgraf]

@matthew-brett would you be willing to upgrade to a newer version of Jupyter Book? A lot of the syntax highlighting has been improved upon. Also, in https://github.com/jupyter/jupyter-book/pull/89 we've got a CLI for creating new books so you should be able to pretty easily generate a new one. It'd be something like

jupyter-book create mynewbook --toc path/to/oldbook/_data/toc.yml --content-folder path/to/oldbook/content --config path/to/oldbook/config.yml

I'd also love feedback on the CLI experience too, in case you have any thoughts :-)

(alternatively, you can also just copy the CSS files from the master branch of jupyter book and that should solve your problems haha)

[matthew-brett]

Haha indeed! Porting the site seems like it's a fair bit of work at this point - I've customized it quite a bit over the last few months.

Of course I did try copying the assets/css directory over, but that just pushed me into a world of pain, which I can describe if you're interested in my legacy applications.

[choldgraf]

ah bummer - if you give me an idea of the way in which you customized, maybe I can help upgrade it? Understand if you'd like to focus on other parts of development though...

[matthew-brett]

Let me reconstruct why I was reluctant to move over. I'll do one comment at a time if I may.

The first issue was the structure. My site uses your old structure, where there is stuff that is not in the textbook (classes, etc), that doesn't appear in the menu, and stuff that is in the textbook, that does. I liked that because I can point people directly to the textbook without them seeing the cruft of the class organization. Of course I could split the website into two books, one with the class pages, one with the textbook, but it's a bit late for that, for the current course.

[matthew-brett]

Then there some customizations, they may work fine or with a little work. I use Jupytext and edit notebooks in R markdown format, so I have a custom script to regenerate the .ipynb files from the .Rmd files, if they are out of date, and then run them, unless they've got some custom values in the YaML header : https://github.com/matthew-brett/dsfe/blob/master/scripts/rebuild_notebooks.py. I have a custom plugin to generate references to the original Data8 sources for some of my pages - see e.g. the end of this page.

Those are the main things.

[choldgraf]

re: the jupytext stuff, first that's really cool! the process of notebook -> markdown hasn't really changed much, so I don't know that the new book would break that

re: the site structure, yeah I explicitly tried to make the "course website" separate from the "course book" in the latest version. It seemed like there was a lot of extra cruft added by building both a course website and a book structure in the same template, so that way you could just link to the textbook from the course site 9and vice versa) and keep those two repositories separable. It was kind of a subjective decision to keep the repository a bit simpler. If you definitely don't want to do that, then yeah you're probably better off sticking with your current setup :-)

[matthew-brett]

Yes, the Jupytext stuff has really transformed the process for me. I hate editing notebooks in the interface, and now I can edit them in nice-looking, round-trippable R Markdown, where I can get my changes in the live notebook by refreshing the browser tab. Shoutout to @mwouts. Game-changer.

[matthew-brett]

For the structure, yes, I completely understand the decision to do textbook-only, and it's probably the right one, but it's too late to do that for my current course.

So, back to haha - any hints for getting the css working so I can see None? What parts do I need? The structure of assets has changed a lot.

[matthew-brett]

Incidentally, while I'm freestyling here, I discovered the beautiful raises-exception tag in Jupyter. In Jupytext R markdown, that is:

```{python tags=c("raises-exception")}
1/0
```

In notebook JSON, it involves adding the following to the cell metadata:

   "metadata": {
    "tags": [
     "raises-exception"
    ]

This allows the notebook to execute without stopping, and generates the exception output, so allowing me to put examples of errors in my notebooks, and still execute each modified notebook when I build the site. Example built page: https://matthew-brett.github.io/dsfe/chapters/07/functions#function-world

[choldgraf]

the raises exception thing is cool! I feel like there's a lot more were can do by using notebook / cell metadata more. and yea I agree that @mwouts is awesome for making jupytext :-)

re: the None thing, couldn't you just add your own CSS rule for that particular class? e.g. to make it red

.highlight .bp {
    color: #cc0000;
}

I believe that the version you're using uses Rouge to generate HTML from the markdown (it's configured in _config.yml anyway). That should systematically choose names for different code elements so you should be able to figure out which classes map to which python elements by looking at those docs

[matthew-brett]

Thanks - your suggestion worked well for a quick fix: https://github.com/matthew-brett/dsfe/commit/4d296dc23e51d8c5d80543d08c0c72a080e3ac0c

[choldgraf]

woot! (think this is closeable now? it's fixed in master so I'm not sure how else to address if ya don't wanna update :-) )

[matthew-brett]

Thanks for the suggestion, yes, nothing for y'all to do here ...w3

[matthew-brett]

Sorry, "w3" was not some hot new internet abbreviation, it was my dogs play-fighting and landing on my computer as I was typing.

[mwouts]

Thanks @matthew-brett and @choldgraf for your positive comments on Jupytext - I really appreciate it!