Get CI audits back to passing

[bollwyvl]

Somewhere between #430 and #425 we regressed on the lighthouse scores, and #294 has raised the bar higher. Let's investigate getting these back to passing, or failing that, loosening the required metrics.

[bollwyvl]

Initial finding:

• Provide more semantic structure for screen-readers sphinx-doc/sphinx#9358 added a role='heading' to all captions
  • this role has a required attribute of aria-level, yet somehow has an implicit value of 2
  • captions appear both in tocs (where they would have a meaningful level) as well as around figures, etc. (where they wouldn't)

[bollwyvl]

Here is a relatively ghetto way to get something in there...

     # overwritten
    def visit_title(self, node: Element) -> None:
        if isinstance(node.parent, addnodes.compact_paragraph) and node.parent.get('toctree'):
            node_level = 1
            parent = node.parent
            while not (
                parent is None or
                isinstance(parent, addnodes.document)
            ):
                parent = parent.parent
                node_level += 1
            #__import__('pprint').pprint(node.parent.parent.__dict__)
            self.body.append(self.starttag(node, 'p', '', CLASS='caption', ROLE='heading', **{'ARIA-LEVEL': node_level}))
            self.body.append('<span class="caption-text">')
            self.context.append('</span></p>\n')
        else:
            super().visit_title(node)
        self.add_secnumber(node)
        self.add_fignumber(node.parent)
        if isinstance(node.parent, nodes.table):
            self.body.append('<span class="caption-text">')

[choldgraf]

hmmm - so this is a regression based on core Sphinx? I don't think that we should write lots of hacky code to un-regress core Sphinx or this is going to be a very painful cat and mouse game. Is there a fix that should be made in Sphinx?

And it sounds like the main problem is that aria-level is not in there...is that right?

Maybe a less hacky way to do this (well, still hacky, but less code) would be to just grab the soup object around here:

https://github.com/pydata/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/__init__.py#L64

and then do something like

for ii in soup.findAll(ROLE="heading"):
  if "aria-level" not in ii.attrs:
    figure-out-level-and-add-it

[bollwyvl]

so this is a regression based on core Sphinx

Yeah, it landed in 4.1.

a very painful cat and mouse game

Yep.

and then do something like...

That might be easier in the near term.... though, as mentioned, captions like this show up in both the toc and next to figures.

[jorisvandenbossche]

@bollwyvl thanks for looking into this! One thing I am wondering: since it's a regression in sphinx, has this already been reported over there as well?