Reduce duplication by including modular text components across notebooks

[danielfromearth]

In co-working today, @ateucher, @jules32, @mjami00, and I discussed ways that we might reduce the duplication of text blocks that describe common resources (such as Harmony, earthaccess, Earthdata Search). We started experimenting in the ASDC tutorials repository (nasa/ASDC_Data_and_User_Services#14), and had a few ideas but still some challenges.

[ateucher]

From the discussion:

• If tutorial developers use includes in their .ipynb notebooks, that include code ({{< include _snippets/harmony.qmd >}}) will be visible to people who are working from the notebooks (as the include is rendered when the site is rendered). Users will see this and it might be confusing. And whole point of a Jupyter Notebook is to have text and code together, this approach is breaking that.

• 3 use cases:

  1. Use during a workshop (user clones repo and works through notebook)
  2. Download .ipynb file and run yourself
  3. Read through rendered page on website - maybe this is most-used case

Use-cases i & ii will display the include code rather than the content from the file which is to be included.

There is a possible path of writing the tutorial in a .qmd document, and also create a .ipynb file when rendering to html. This requires setting in the yaml header:

format:
   html: default
   ipynb: default

This still has two problems:

• It is asking tutorial developers to write their tutorials in qmd docs instead of Jupyter notebooks, which is a big change
• We would need to ensure that the ipynb file is committed in the main branch so that when tutorial participants clone the repo, they can find it. If rendered in an action, would need some intervention to commit it to the main branch... very annoying from a maintenance standpoint.

Writing in .qmd, but using keep-ipynb: true is also an option, but it creates a file with .quarto_ipynb extension, so manual renaming would be necessary...

Relevant issue: quarto-dev/quarto-cli#8533

[ateucher]

Note from the Quarto includes documentation:

Computational includes work only in .qmd files (they don’t work in .ipynb notebook files)