Formulate learning goals at top of each topic.

[timosachsenberg]

Maybe in a colored box e.g. something like

In this section, you will learn:

• how to load, process and store mass spectra and chromatograms
• how to plot spectra

[enetz]

I tried to see what options there are, and it seems making random colored boxes with rst is not trivial.
To keep it simple, we can use the "Note" boxes or just an indented list. We don't use those note boxes very often yet.
Here is an example how these two options would look like:

[timosachsenberg]

I think the note boxes don’t look bad

[jpfeuffer]

Can you try admonition?
https://labs.bilimedtech.com/workshops/rst/writing-rst-3.html

We also have to check if it is correctly converted to ipynb.

[enetz]

@jpfeuffer thanks for that link! I tried to find a way to define custom admonitions, but couldn't find an example before, so I tried the Note default.

[enetz]

also about jupyter compatibility, I didn't expect this, using binder:

It turns into simple plain text with Note above (example from a page where a Note was already used before),
although jupyter supports the same admonitions, just with a slightly different syntax.
It looks like it should be trivial to translate: https://jupyterbook.org/content/content-blocks.html

[jpfeuffer]

Yes.. unfortunately not supported by pandoc:
jgm/pandoc#2610

We would need a custom filter.

[timosachsenberg]

if it is only about the learning goals I think we could also go with the special ignore tag for binder?

[jpfeuffer]

I quickly hacked another pandoc filter:

#!/usr/bin/env python

"""
Pandoc filter to convert divs with class="admonition" to ipynb
"""

import sys
from pandocfilters import toJSONFilter, RawBlock, Div, stringify


def html(x):
    return RawBlock('html', x)


def admonitions(key, value, format, meta):
    if key == 'Div':
        [[ident, classes, kvs], contents] = value
        if "admonition" in classes and format == "ipynb":
            newcontents = [html('<div style="background-color: #BDE5F8; margin: 10px 0px; padding:12px;"><p><i class="fa fa-info-circle"></i> <b>' + stringify(contents[0]) + '</b></p>')] + contents[1:] + [html('</div>')]
            return Div([ident, classes, kvs], newcontents)
        elif "note" in classes and format == "ipynb":
            newcontents = [html('<div style="background-color: #BDE5F8; margin: 10px 0px; padding:12px;"><p><i class="fa fa-info-circle"></i> <b>Note:</b></p>')] + contents + [html('</div>')]
            return Div([ident, classes, kvs], newcontents)

if __name__ == "__main__":
    toJSONFilter(admonitions)

[jpfeuffer]

But not sure how well that works with nestedness.

[jpfeuffer]

By the way, I could not make the admonitions work without HTML in binder. I don't think it supports the full jupyterBOOK format.

[jpfeuffer]

filter was included in #212

[tapaswenipathak]

What are the remaining documentation todos?

[jpfeuffer]

Add learning goals to top of every "applied"/tutorial section of the pyopenms and maybe also the new openms docs.

[timosachsenberg]

any update here from last sprint?

[KyowonJeong]

Yes. I studied how to put this box and tried a few things. I will try to put this box in each algorithm section by the next week.