question about outlining *notes* cells in the html output

[parmentelat]

Hey there again

I'm happy with my current setup, and would just like to implement one last tweak; in a nutshell I'd like to customize my html output so that cells that are marked as notes (in terms of the slideshow-oriented) show up with some customized styling - I'm thinking CSS

I've read the readthedocs manual, my feeling is that what I'm after is quite possible but all the notions in there are still quite abstract to me, so if anyone could hint me at how to start tackling this, I'd be most grateful

and thanks again for this great and super useful tool :)

[chrisjsewell]

So the 'easiest' way to do this is to create a pre-processor, that wraps the text of relevan cells in a sphinx directive. Then copy the relevant configuration file (e.g. sphinx_ipypublish_all.ext.noexec) and add the preprocessor see here.

Off-the-cuff, the pre-processor would look something like this:

from textwrap import indent
from nbconvert.preprocessors import Preprocessor

class NotesToSphinx(Preprocessor):
    def  preprocess_cell(self, cell, resources, index):
        if cell.cell_type != "markdown":
             return cell, resources
        if "slide" in cell.metadata and cell.metadata["slide"] == "notes":
            cell.source = ".. note:\n\n" + indent(cell.source)
        return cell, resources

[chrisjsewell]

PS let me know if there are any additions to the documentation, that would make it easier for first time users, ta

[parmentelat]

Thanks for the tip ! I will make sure to report back on this channel when I have a chance to try it out, probably over the next coming weeks

Cheers

[parmentelat]

Also, to be sure I understand, I take it the preprocessor would add a class to the associated

tag - since IIRC that’s what I get right now, right ?

What’s the recommended way to drop my CSS snippet in the chain then ?

Sent from my iPhone

On 14 Aug 2019, at 15:28, Chris Sewell notifications@github.com wrote:

PS let me know if there are any additions to the documentation, that would make it easier for first time users, ta

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[parmentelat]

hello

I've given all this a try; I was able to configure the workflow and have my preprocessor trigger - and indeed I could gather some material to add in your doc, like where to store my custom json, how to make it findable, and same for the preprocessor python module.

I'm still a little confused though, because I'm seeing this as an outcome

What's odd here is that the actual cell content is the whole sentence from La vidéo introductive montre
all the way until
avoir du mal à en voir la finalité

that cell source fits in a single line in the notebook, but somehow it gets split in the process
this is repeatable on all my other notes cells

Not knowing the best way to troubleshoot this, I have instrumented my custom preprocessor and here's what cell.source contains before and after it gets preprocessed

======================================== avant
La vidéo introductive montre, à très haute altitude, comment git peut être utilisé dans un workflow très simplifié mais assez typique. Naturellement toutes ces notions sont reprises par la suite, il s'agit uniquement de fixer les idées, notamment pour les gens qui n'ont aucune idée a priori sur cet outil, et qui pourraient avoir du mal à en voir la finalité.
======================================== après
.. note::
   La vidéo introductive montre, à très haute altitude, comment git peut être utilisé dans un workflow très simplifié mais assez typique. Naturellement toutes ces notions sont reprises par la suite, il s'agit uniquement de fixer les idées, notamment pour les gens qui n'ont aucune idée a priori sur cet outil, et qui pourraient avoir du mal à en voir la finalité.

also I have mentioned my custom preproc as the last preprocessor in the list

I have been able to check in simpler plain sphinx files that this RST fragment should work fine

it all suggests that something down the road messes with this contents, but I have no clue how to tell what that something is

does that ring any bell to you; how would you go about troubleshooting this ? is there any resource that tells how to inspect a notebook at the different stage of an nbconvert worflow ?

thanks in advance

[chrisjsewell]

1. There should be a blank line between .. note:: and the text, that might help?
2. If you just use a version of sphinx_ipypublish_all, with your preprocessor added, directly on the notebook: nbpublish -f sphinx_ipypublish_all your_notebook.ipynb. This will only convert the note book to RST, without running sphinx. Then you can see exactly what is being input into Sphinx.
3. In the preprocessor that I suggested, you are modifying the source text, but leaving the cell as a markdown cell. Then the ipubpandoc 'magic' is preserving the RST elements, during the conversion from markdown to RST. You can use pandoc -f markdown -t rst --filter ipubpandoc test.md to test how this is working. I noted that your indentation (with 3 spaces) did not work, but with 4 spaces it does, i.e.:

test.md

.. note::

    La vidéo introductive montre, à très haute altitude, comment git peut être utilisé dans un workflow très simplifié mais assez typique. Naturellement toutes ces notions sont reprises par la suite, il s'agit uniquement de fixer les idées, notamment pour les gens qui n'ont aucune idée a priori sur cet outil, et qui pourraient avoir du mal à en voir la finalité.

4. Alternatively, to by-parse ipubpandoc, in your pre-processor you would need to change the cell type to a raw cell. However, any markdown specific syntax would not then be converted.

[parmentelat]

thank you for all the tips

indeed I could get this to work with 4 spaces, no need to mark the cell as raw; there are currently a few limitations on what I can use in the notes - itemized lists and code blocks cause fatal errors down the line - but that's quite workable for me at this point

the outcome for my first use case can be seen here - sorry it's in French
https://flotpython-gittutorial.readthedocs.io/fr/latest/1-01-summary-video.html

preproc is here
https://github.com/flotpython/gittutorial/blob/master/notebooks/custom/outlinenotes.py

enabling the preproc in JSON here
https://github.com/flotpython/gittutorial/blob/master/notebooks/sphinx_ipypublish_all.ext.custom.json

tweaks needed in the sphinx conf.py, so that it (1) finds the json in cwd, and (2) finds the preprocessor that I currently ship with the notebooks
https://github.com/flotpython/gittutorial/blob/master/notebooks/conf.py#L23-L28

I'm kind of in a rush right now, but I plan on publishing this preprocessor on pypi - if only because I need this on several rtd instances and want to avoid duplication; as part of that I'll try to summarize how to enable it

thanks again !