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

[Mauro Carvalho Chehab]

Em Fri, 13 Jun 2025 14:26:44 +0200
Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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