[WIP] Documenting all options of the FrameworkBundle

[wouterj]

Let's give one of the most forgotten dark places of the documentation some love :)

It's quite a difficult job, since I have to document lots of things I'm normally not very interested in (and thus do not know much about). So I hope the core team can help me verify the documentation in this PR. (cc @stof @jakzal)

Q	A
Doc fix?	yes
New docs?	yes
Applies to	2.3+
Fixed tickets	not sure

[stof]

this XSD schema is not the XSD schema of the FrameworkBundle config. It is the XSD schema of the DI component (not the same XML namespace)

[wouterj]

http://symfony.com/schema/dic/services is the DI component, isn't it?

https://github.com/symfony/FrameworkBundle/blob/master/Resources/config/schema/symfony-1.0.xsd is in http://symfony.com/schema/dic/symfony/symfony-1.0.xsd

[stof]

ah right sorry

[xabbuh]

Is it a good idea to link to the schema file on symfony.com since we may have different versions of it in the branches on GitHub but only one version on symfony.com?

[wouterj]

The schema is not retrieved by requesting the url. Symfony's Xml parser replaces the configured extension namespace with the file path returned from getXsdValidationBasePath().

The FrameworkExtension looks like:

class FrameworkExtension // ...
{
    // ...
    /** 
     * Returns the base path for the XSD files. 
     * 
     * @return string The XSD base path 
     */ 
    public function getXsdValidationBasePath() 
    { 
        return __DIR__.'/../Resources/config/schema'; 
    }. 

    public function getNamespace() 
    { 
        return 'http://symfony.com/schema/dic/symfony'; 
    } 
}

So http://symfony.com/schema/dic/symfony/symfony-1.0.xsd becomes path/to/FrameworkBundle/Resources/config/schema/symfony-1.0.xsd which is the right schema in the right version

[xabbuh]

I know how the DependencyInjection handles schemas defined by a bundle. I was just referring to your tip. People might think that they can lookup the actual schema file under this url and that may confuse them.

[wouterj]

Thanks for your time and feedback @stof!

[xabbuh]

I would use a complete valid XML file here.

[wouterj]

What's the point of that?

[xabbuh]

With complete I mean adding the "header". This way, you can copy the example without having to investigate the proper namespace and schema definition and so on.

[stof]

btw, this is broken. The closing tag should be </framework:config>

[stof]

and this is broken in all XML snippets

[xabbuh]

Looking at Travis, this needs to get its own label to not be confused with fragments.path.

[xabbuh]

@wouterj Is there anything left to do (besides rebasing)?

[wouterj]

@xabbuh not all options are documented. I'll work on this after I've done some big refactoring in the CmfMenuBundle.

[wouterj]

Wrong rebase + messy PR = new PR: #4736