Add pa11y test for web accessibility checks of built content

[d33bs]

Description

This PR adds a test using pa11y to ensure web accessibility for the built content. While adding this I noticed there were issues with several existing checks. The fixes for these I believe involve deeper modifications to the templates being used by jupyter-book. In the meantime, I've added rules to ignore them so tests may pass. If all looks good here, I plan to open an issue to cover future modifications.

Details below (referencing ignores from pa11y.json):

// search form has no submit button
"WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2",
// heading tags detected with no content
"WCAG2AA.Principle1.Guideline1_3.1_3_1.H42.2",
// search form duplicate id
"WCAG2AA.Principle4.Guideline4_1.4_1_1.F77"

Closes #4

What is the nature of your change?

• Content additions or updates (adds or updates content)
• Bug fix (fixes an issue).
• Enhancement (adds functionality).
• Breaking change (these changes would cause existing functionality to not work as expected).

Checklist

Please ensure that all boxes are checked before indicating that this pull request is ready for review.

• I have read the CONTRIBUTING.md guidelines.
• My code follows the style guidelines of this project.
• I have performed a self-review of my own contributions.
• I have commented my content, particularly in hard-to-understand areas.
• I have made corresponding changes to related documentation (outside of book content).
• My changes generate no new warnings.
• New and existing tests pass locally with my changes.
• I have added tests that prove my additions are effective or that my feature works.
• I have deleted all non-relevant text in this pull request template.

[vincerubinetti]

This looks good, I'm glad you took the initiative to add this. Could you add just a brief justification somewhere (perhaps the readme) of why each of those rules is ignored. The middle one, H42.2, is slightly worrying, as there really shouldn't be empty headings. The other two rules are at least dealable-with.

Just something to pinpoint exactly where the error in the HTML is coming from, to distinguish it from an actual error that might need attention. Something like "Jupyter interface does not correctly add type="submit" to play button" (or whatever it is). Or, "Empty headings caused by anchor links improperly using tags" (just guessing). I could see how Jupyter might duplicate document ids, like if the author has multiple sections in their documents called e.g. "Results" and doesn't distinguish them like results-1/2/... (as most tools do).

I see you considered AXE. From what I've observed in the industry, AXE is the golden standard. Lighthouse is based on AXE (and adds some extra things I think). Is there a reason you chose pa11y over that? I see it does have more installs, but axe-core has more github stars. I dont think there's a need to completely redo the PR to switch to that -- a second-best accessibility test is way better than none at all -- just curious.

[d33bs]

Thanks @gwaybio and @vincerubinetti ! Addressing your comments below:

Could you add just a brief justification somewhere (perhaps the readme) of why each of those rules is ignored.

I'll go ahead and open the issue I mention in the description of this PR to keep this actionable. From there, I plan to open issue(s) with the jupyter-book project to demonstrate the exact issues with their default template. If we can receive a fix from upstream, that'd be best I feel (as this likely impacts many jupyter-book sites), but otherwise maybe the devs have a workaround they'd suggest.

I see you considered AXE. From what I've observed in the industry, AXE is the golden standard. Lighthouse is based on AXE (and adds some extra things I think). Is there a reason you chose pa11y over that?

I was dissuaded from using AXE because the linter portion of their platform seems to be for-pay (link) and I felt unsure about the challenges associated with that (in terms of funding, licensing, and demonstrating open-source tooling which anyone may use). Lighthouse doesn't seem to have built-in "linting" capabilities (i.e. zero/non-zero returns) and though I know it can be configured through reporting to do so this would take extra time. Pa11y is reasonably popular, was quick to configure for this project, and appears to have an active community so I thought we could give it a try.

[d33bs]

Thanks @vincerubinetti !