Draft: Quarto docs

Context

Change doc website from Sphinx to Quarto.

Summary of changes

• Function documentation is now automatically generated with quartodoc, which is explicitly designed as a quarto-friendly alternative to Sphinx.
• Translated the other documentation files, including the meta, simple examples, and workflow notebooks, from rst to qmd. The transition wasn't 100% seamless and did require me to manually edit some of the code, but this could be because I didn't install the JupyterLab quarto extension first.
• Moved .png files into a new "images" folder since "reference" is now reserved for function documentation.
• Copied the README.md file contents over to the main index.qmd file that sits at the root of the website.

Requested review

One part of the review will be verifying that someone else can also build the website locally. The other part will be commenting on changes you'd like to make. None of this is set in stone. It is merely my first attempt at re-creating the Sphinx site and adding some other structure.

1. Open a command line interface and set the working directory to the repo's root folder.
2. Install quartodoc with python -m pip install quartodoc.
   • Make sure you have Quarto installed also.
3. Run python -m quartodoc build --config ./docs_quarto/_quarto.yml to build the docs file. If all works correctly, you shouldn't see any output in the CLI (I didn't at least). Verify that this created qmd files in the docs_quarto/reference folder.
4. Preview the website with quarto preview docs_quarto.
5. Navigate through the website pages, noting any changes you'd prefer to make.
6. Open the docs_quarto/_quarto.yml file. This file dictates the overall structure of the package website, so it's important to be accustomed with its contents if you want to make changes/updates. See https://quarto.org/docs/websites/ for Quarto website documentation.

Next steps

• Set up a GitLab CI job to rebuild documentation rather than pushing all the HTML files in a local docs/ folder.
• Replace docs/ folder with content of docs_quarto once we're happy with the new site.
• Change website theming, add Google Analytics tag, add light/dark mode toggle(?)
• Figure out if we can make any of the example notebooks interactive using quartolive.

Open questions:

• How to synchronize README.md with main index.qmd?
• How to add dependency graph image to reference/index.qmd file? This is automatically generated by quartodoc, so any "manual" changes we make would likely be overwritten whenever the docs are re-built. We could look through the quartodoc/quarto documentation to determine whether we can specify additional figures in the _quarto.yml file.
• How to link to an element of a table cell (e.g., Glossary)? This wasn't a feature as late as January, 2023, but perhaps it can be done now? Otherwise, we could change the glossary to a non-table format that would permit cross-referencing.