Introduce a format to comment YAML files and make it parseable

TYPO3 Association Budget 2022
1

Application by
Lina Wolf

What is your idea about?
YAML is more and more used as a format for the configuration
in both the core and extensions. The use will probably spread
in the future. Right now the following aspects of TYPO3 use YAML
quite heavily:

  • site configuration
  • services configuration
  • configuration of the RTE
  • configuration of the form framework
  • form definitions
  • configuration of functional tests.

YAML provides a plain comment syntax. At the moment comments are
used sparingly within the TYPO3 core. At times it cannot be
determined to which line or level a comment belongs. Some
comments refer to several configuration blocks etc.

We would like to introduce a special format for YAML comments
similar to PHPdoc. The format is well-defined and can be parsed
automatically.

The parsed comments can then be used to enricht the Configuration
module in the TYPO3 backend and enables us to generate a
documentation of YAML configurations automatically. In the future
those comments could even be used by a general editing tool.

What is the potential impact of your idea?
New developers and integrators of TYPO3 struggle with a
steep learning curve. As TYPO3 has been growing, many different
configuration formats have been introduced: TypoScript for
constants and setup, global extension configuration, TSconfig for
pages and users, all of them internally translated into PHP arrays.
Then pure PHP arrays for TCA, Global variables etc. Add YAML in
different contexts to the package, this is a huge body of learning.

The steep learning curve is what often keeps developers from
wanting to learn TYPO3. And as TYPO3 developers are in short
supply it is not easy for agencies to attract talents to TYPO3.

We want to flatten the learning curve by giving easier access to
understanding YAML configurations.

Who can / should implement your idea?
I will take care myself

Approximate Funds needed
€5,000 - €10,000

4 Likes
2

Having this would be awesome. I have to deal with the form documentation. The form framework ships tons of YAML. The documentation has trouble with all the YAML stuff in it. We have to maintain it manually. No chance!

Big +1 for this budget application.

3 Likes
3

The problem is that YAML is not only read but also written by TYPO3. So TYPO3 would need to use a custom YAML parser not only for creating documentation.

I’m not a big fan of XML for configuration, but this would make embedding documentation much easier.

A solution could be using special prefixes for keys to denote a comment. eg “foo” will be documented by “@foo”.

4

I once did some work in this area which can be found at GitHub - georgringer/site-config-validation: Use schema json validation. this improves working with those yaml files a lot! maybe as inspiration

6 Likes
5

A quick research tells me that there is no specific schema format for YAML. As both JSON and YAML describe language-agnostic data types and structures the recommendation is to use the established (formally?) JSON schema and apply it to YAML. There are even existing tools that do the job.

A structural linter and/or schema validator is a big help when dealing with YAML files. Thumbs up for YAML schemas.

1 Like