Standardize formatting to improve accessibility

[troyraen]

First, check whether there are any general accessibility guidelines about formatting. My guess is that the guidelines are to follow language-specific standards and style guides. In that case, the lists below are what I think we should start with.

For this issue, update the notebooks listed in #184 so they can be reviewed by the external consultants. We'll use the experience to create a plan for other current and future notebooks.

Python:

• Follow PEP 8 (the baseline python style guide)
  • In .py files, this can be done pretty easily using autopep8 to automatically fix issues like spacing and flake8 to flag other issues like unused imports that need to be checked and corrected manually. (And flake8 may flag some things we choose to ignore.)
  • Jupytext can be used to convert markdown files .md <--> .py so autopep8 and flake8 can be used on code cells. However, the conversion process may change some things that we don't want changed (like how code cells are delineated) so be careful about what changes get committed. If preferred, the code cells could be manually copied to and from a .py file rather that using jupytext to convert the whole file. Alternately, an LLM may be able to mimic autopep8 and flake8 and operate directly on the .md files.
• Enforce max line length of 90. There are good reasons for using a consistent max line length, though the specific number chosen by a project tends to range between 80 - 120 in my experience. I think we should use 90 because it should make all code in the rendered notebooks viewable without having to scroll horizontally.

Markdown (This applies to markdown cells in .md files. For python code cells in .md files, see above.):

• Find a markdown linter that's easy to use and does the basics of what we need. Use it on the notebooks listed in 184.
  • Some options are markdownlint, PyMarkdown, and markdownlint for vscode.
  • My understanding right now is that the most important things for accessibility are consistent use of heading levels and consistent spacing between characters and lines.
• Enforce one line per sentence. There are 2-3 schools of thought in the published standards/guidelines. For accessibility purposes, my guess is that it's most important to choose one and use it consistently. We've discussed it in the past and chosen one line per sentence, in large part because it produces the smallest diffs for PR reviews.

[bsipocz]

Enforce one line per sentence. There are 2-3 schools of thought in the published standards/guidelines. For accessibility purposes, my guess is that it's most important to choose one and use it consistently. We've discussed it in the past and chosen one line per sentence, in large part because it produces the smallest diffs for PR reviews.

I would be very much in favour of this. If a sentence comes back too long, then its a copyediting issue rather than something for a linter to brute force as cutting up the long sentence would help making it more understandable. (this, in addition to the argument of smaller diffs for easier review)

[troyraen]

To clarify, the goal here is to prep for the consultants' notebook review (see parent issue), so not necessary to spend a lot of time tracking everything down. I think some of these things will be easy to do and we should just do them. But other things might prove to be less straight forward and for those it would be good to just play around with tools a little so we know what's available and then come up with a rough plan or questions that we can get the consultants' input on.

[troyraen]

The consulting firm is already evaluating notebooks, so it's not strictly necessary to make changes to these three but it will still be good to try these things out and come up with a plan.