[DX] Improving documentation when multiple languages are possible

[ajanssens]

Symfony 2 comes with a lot of possibilities when it comes to configuration : YAML, XML or plain old PHP.
We also have sometimes the choice to use Annotations. As for the templating there's Twig and PHP.

Most of the time documentation is well referenced with every languages but there's still a few pages where we can only find YML when XML and PHP are possible like this one : http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/routing.html

I've made a PR (sensiolabs/SensioFrameworkExtraBundle#325) to cover a few gaps but, by example, I don't really know how to set "type Annotation" from an import in PHP.

Here is some other pages when languages are missing :

http://symfony.com/doc/current/book/propel.html : config.yml only, then XML for schema. I'm not using Propel but i'm asking myself : can't I use YAML here ? Or even Annotations ?

http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html#creating-a-converter : In this one converter service only in YAML and XML. PHP is missing.

I think there's a bit more of them. A really few, I'd like this DX Issue to be a first move to track this pages down and fill the gaps :)

[stof]

All these places are occuring in doc provided in external repos. This issue has already been fixed for the main symfony documentation a few months ago by ensuring we have all formats everywhere.
the right thing to do is to contribute to each repo to add the missing formats.

but, by example, I don't really know how to set "type Annotation" from an import in PHP.

The Loader::import method receives the type as its second argument

[xabbuh]

@stof Actually, the Propel chapter is part of the book.

[stof]

hmm, indeed

[wouterj]

The propel book does only show configuration snippets from app/config/parameters.yml. It doesn't make sense to use other formats there (we don't do that in other places in the docs too).

Afaik, you can only use XML when configuring Propel or did that change in the past? If this is correct, the propel book does not miss anything.

[wouterj]

Closing as the Propel book is going to be removed (#4900) and the other examples are from third party bundles, which should be fixed and reported in their repository. I'm almost 100% sure that the core docs documents every format everywhere.