Including the tutorials

[abkfenris]

A first pass at including the tutorials on the website

[netlify]

✅ Deploy Preview for oceanhackweek-preview ready!

Name	Link
🔨 Latest commit	44e4d97
🔍 Latest deploy log	https://app.netlify.com/sites/oceanhackweek-preview/deploys/62f99ecd7ea1c0000951c207
😎 Deploy Preview	https://deploy-preview-199--oceanhackweek-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[abkfenris]

It looks like if a notebook doesn't have a clear title, then Sphinx gets cranky and won't include it.

ohw22/tutorials-index/data-access-in-python.md:3: WARNING: toctree contains reference to document 'ohw22/tutorials/01-Tue/00-data-access-in-python/03-extras-argopy-erddap' that doesn't have a title: no link will be generated
ohw22/tutorials-index/espanol/python-cientifico.md:3: WARNING: toctree contains reference to document 'ohw22/tutorials/optional/espanol/python-cientifico/intro_to_python_ohw2022' that doesn't have a title: no link will be generated
ohw22/tutorials-index/espanol/python-cientifico.md:3: WARNING: toctree contains reference to document 'ohw22/tutorials/optional/espanol/python-cientifico/Intro_to_plot' that doesn't have a title: no link will be generated
ohw22/tutorials-index/espanol/python-cientifico.md:3: WARNING: toctree contains reference to document 'ohw22/tutorials/optional/espanol/python-cientifico/intro_to_netcdf' that doesn't have a title: no link will be generated
ohw22/tutorials-index/data-access-in-python.md:3: WARNING: toctree contains reference to document 'ohw22/tutorials/01-Tue/00-data-access-in-python/03-extras-argopy-erddap' that doesn't have a title: no link will be generated

https://github.com/oceanhackweek/oceanhackweek.github.io/runs/7828057427?check_suite_focus=true#step:4:353

This happens even if you try to give it an explicit title in the toctree, so there may be some cleanup of tutorial notebooks that we may want to do if we want to include them on the site.

[emiliom]

Wow, thank you! Looks awesome, even more so for a first try.

It looks like if a notebook doesn't have a clear title, then Sphinx gets cranky and won't include it.

I'll work on adding titles to the notebooks in ohw22/tutorials-index/espanol/python-cientifico.md, hopefully (if I can muster it) by tomorrow morning.

Question: how does it handle R notebooks (or whatever the right R terminology is)? For the Rmd files in https://github.com/oceanhackweek/ohw-tutorials/tree/OHW22/01-Tue/00-data-access-in-R, it looks like that's what it's doing. It's not ding it for the ones in https://github.com/oceanhackweek/ohw-tutorials/tree/OHW22/optional/espanol/datos-espaciales-tidy, but I'm guessing it's b/c the extra packages in that tutorial are not in the live R image yet. If a *.nb.html file exists, does it use it if there's no *.Rmd file with the same base name?

[abkfenris]

Wow, thank you! Looks awesome, even more so for a first try.

It looks like if a notebook doesn't have a clear title, then Sphinx gets cranky and won't include it.

I'll work on adding titles to the notebooks in ohw22/tutorials-index/espanol/python-cientifico.md, hopefully (if I can muster it) by tomorrow morning.

Thanks, then I don't have to invent what things might be called. Please suggest edits for anything I've putzed the spelling up on.

Question: how does it handle R notebooks (or whatever the right R terminology is)? For the Rmd files in https://github.com/oceanhackweek/ohw-tutorials/tree/OHW22/01-Tue/00-data-access-in-R, it looks like that's what it's doing. It's not ding it for the ones in https://github.com/oceanhackweek/ohw-tutorials/tree/OHW22/optional/espanol/datos-espaciales-tidy, but I'm guessing it's b/c the extra packages in that tutorial are not in the live R image yet. If a *.nb.html file exists, does it use it if there's no *.Rmd file with the same base name?

Juyptext is reading the Rmd, but I don't think it uses the .nd.html.

I don't believe I included https://github.com/oceanhackweek/ohw-tutorials/tree/OHW22/optional/espanol/datos-espaciales-tidy which would be why it's not displaying.

[emiliom]

Juyptext is reading the Rmd, but I don't think it uses the .nd.html.

Thanks. I've been looking into Jupytext for doing this in a Jupyterbook, but w/o necessarily having an R conda env to execute the notebook. I assume in this case it's reusing the OHW22 R conda env to execute the Rmd's? Otherwise, unlike a pre-executed Jupyter notebook, Rmd notebooks don't include the output.

[abkfenris]

Juyptext is reading the Rmd, but I don't think it uses the .nd.html.

Thanks. I've been looking into Jupytext for doing this in a Jupyterbook, but w/o necessarily having an R conda env to execute the notebook. I assume in this case it's reusing the OHW22 R conda env to execute the Rmd's? Otherwise, unlike a pre-executed Jupyter notebook, Rmd notebooks don't include the output.

Neither Jupyter nor R notebooks are getting executed, so it's just whatever they are saved with. I think Sphinx can directly include basic .html files, which I tried when there was one alongside an .Rmd, but I didn't spend much time trying to debug why it wasn't working.

[emiliom]

I see. Thanks. I won't spend more time thinking about it either, until OHW is over.

[emiliom]

It would be great, user-friendliness wise, if the TOC that's generated in https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/index.html could be trimmed to only 2-levels deep, or heck maybe just one-level deep (Getting started, plus the list of tutorials).

Also in https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/index.html (and likewise https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/data-access-in-python.html), the TOC for Data access in Python is weird. The 00- notebook's sections get fleshed out in excruciating detail, and then the last two notebooks (02- and 04-) appear at the end as single TOC entries that might as well be another section in 00-.

Anyways, just observations. I'd go ahead and merge the PR. IMHO having the tutorials on the web site like you have done, despite these quirks, is more helpful than not having them.

[abkfenris]

It would be great, user-friendliness wise, if the TOC that's generated in https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/index.html could be trimmed to only 2-levels deep, or heck maybe just one-level deep (Getting started, plus the list of tutorials).

Tweaked

Also in https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/index.html (and likewise https://deploy-preview-199--oceanhackweek-preview.netlify.app/ohw22/tutorials-index/data-access-in-python.html), the TOC for Data access in Python is weird. The 00- notebook's sections get fleshed out in excruciating detail, and then the last two notebooks (02- and 04-) appear at the end as single TOC entries that might as well be another section in 00-.

I think that's the header depth from the notebooks themselves not being super clear. We can do a pass over the tutorials afterwards producing outputs and cleaning up hierarchy.

[emiliom]

Great. Looks much better. Merge while you're ahead.

[abkfenris]

Great. Looks much better. Merge while you're ahead awake.

FIFY