Documentation

So we have this whole documentation thing set up! It’s pretty cool. This page aims to be a sort of meta-documentation. Documentation about the documentation! But seriously, we need to talk about all the pieces that make up this documentation, and why it is the way that it is.

This documentation uses Sphinx to generate documentation. Sphinx is great because it allows easy generation of HTML or PDF from markup languages like ReStructured Text (RST). ReStructured Text is different than Markdown, and the learning curve is a bit higher, but it’s generally better for documentation and has more advanced and more stable feaetures.

Template and Theme Used

I (Lavender Shannon) have used Sphinx quite a bit in the past, so generally whenever I am starting a new project, I copy the important files like docs/source/conf.py and docs/Makefile and docs/preview.sh into my new project. However, it’s worth noting that this setup is very similar to https://github.com/readthedocs/sphinx_rtd_theme

Most of my documentation projects use the Furo theme, as it has light/dark mode, and its sidebar can be navigated without leaving the page you are on.

readthedocs.io

https://readthedocs.org is a website to freely host your documentation. It works great with Sphinx documentation. This website is hosted on https://gradema.readthedocs.io/en/latest/ of course!

Currently Lavender Shannon is the owner of the Gradema Read the Docs project. If someone needs access, I can happily give access, but generally it is not required as long as the GitLab webhook configured at https://gitlab.com/classroomcode/gradema/gradema/-/hooks is not altered.

The file .readthedocs.yaml contains configuration that helps define

Links to help you figure out the webhook if you need to do that:

• https://docs.readthedocs.io/en/stable/guides/setup/git-repo-automatic.html

• https://docs.readthedocs.io/en/stable/reference/git-integration.html

• https://docs.readthedocs.io/en/stable/integrations.html

• https://readthedocs.org/dashboard/gradema/integrations/create/

ReStructured Text

To write good documentation, you’ll need a solid understanding of ReStructured Text. Here are some helpful links:

• https://docs.anaconda.com/restructuredtext/index.html

You may see stuff like .. code-block:: shell in the documentation to specify code blocks. That shell syntax highlighter is apart of Pygments, and its available lexers can be found here: https://pygments.org/docs/lexers/

sphinx-autoapi

The documentation contains autogenerated pages that describe the public API of Gradema. We are using Sphinx AutoAPI for this: https://sphinx-autoapi.readthedocs.io/en/latest/index.html

TODO

The documentation isn’t perfect. Here’s a list of some things to improve on:

• Something like gradema/blob/c08f0799f15073c7ddbe84e7847cbdafe4776d9a/gradema/test/_python.py#L18 shows a place where a docstring references the documentation directly, by URL. We should come up with a way to avoid that.