Re: [PATCH v2 09/12] docs: sphinx: add a parser template for yaml files

Mauro Carvalho Chehab
2025-06-13T15:42:12Z

Em Fri, 13 Jun 2025 14:26:44 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> > > +
> > > + supported = ('yaml', 'yml')
> >
> > I don't think we need to support the .yml extension.
>
> Ok, will drop "yml".

"supported" is not just extensions. It is a list of aliases for the
supported standard (*), like:

supported = ('rst', 'restructuredtext', 'rest', 'restx', 'rtxt', 'rstx')
"""Aliases this parser supports."""

(*) see: https://www.sphinx-doc.org/en/master/_modules/docutils/parsers/rst.html

Anyway, I tried with:

supported = ('yaml')

but it crashed with:

sphinx.errors.SphinxError: Source parser for yaml not registered

On my tests, if "supported" set has just one element, it crashes.

On this specific case, this, for instance, works:

supported = ('yaml', 'foobar')

Anyway, not worth spending too much time on it, as it could be
a bug or a feature at either docutils or sphinx. As we want it to
work with existing versions, I'll keep it as:

supported = ('yaml', 'yml')

at the next version.

> > > +def setup(app):
> > > + """Setup function for the Sphinx extension."""
> > > +
> > > + # Add YAML parser
> > > + app.add_source_parser(YamlParser)
> > > + app.add_source_suffix('.yaml', 'yaml')
> > > + app.add_source_suffix('.yml', 'yaml')
> >
> > No need to support the .yml extension.

Dropping .yml works here. So, here I'll keep just:

# Add YAML parser
app.add_source_parser(YamlParser)
app.add_source_suffix('.yaml', 'yaml')

Regards,
Mauro