Add support for extension configuration

[wouterj]

Allows per-extension configuration:

<?xml version="1.0" encoding="UTF-8" ?>
<guides>
    <extension class="phpDocumentor\Guides\Code">
        <highlighter-language label="php+attribute">php</highlighter-language>
    </extension>
</guides>

And global configuration (which underneeds gets automatically applied to the GuidesExtension):

<?xml version="1.0" encoding="UTF-8" ?>
<guides>
    <project title="Project Title" version="6.4"/>
</guides>

[greg0ire]

I think the XML snippet in the PR description could be used in https://github.com/phpDocumentor/guides/blob/main/docs/configuration.rst

[linawolf]

@wouterj could we integrate intersphinx configuration (#494) into this somehow?

[linawolf]

@wouterj @greg0ire what is needed to make this work?

[greg0ire]

@linawolf I don't understand the question. Are you saying it does not work?

[linawolf]

@greg0ire Some tests are still red and it needs to be rebased so we can merge it

[greg0ire]

Ok: what needs IMO to be done for this to be mergeable:

• fix the cs issue
• either address or ignore the static analysis issue
• add documentation
• add tests if possible

[linawolf]

@wouterj @greg0ire I was trying to add a functional test, however it seems like it has not effect. I don't really understand how this is supposed to work so could someone ™️ support me here?

[greg0ire]

This PR allows to build a configurable highlighter, but does not build it itself, that's part of what #475 is for.

[linawolf]

@greg0ire is there anything that we can already test with an integration test? I still don't understand how this works or how to use the configuration. Not even if my example file is named correctly and in the correct place

[wouterj]

The second snippet with <project title="Project Title" version="6.4"/> is already implemented.

Each extension defines its configuration in the getConfigTreeBuilder() method: https://github.com/phpDocumentor/guides/pull/482/files#diff-a98cf5815ab9d23df43257abd002a77c5792f02cff4ef0ee5add504533a9d8cbR36

The Config component parses the XML and finds the nested nodes from the config tree based on this. So for a <project> XML element, it'll find the arrayNode('project') and the title="..." attribute is mapped to the scalarNode('title') child.

This is then processed by the Config component (https://github.com/phpDocumentor/guides/pull/482/files#diff-a98cf5815ab9d23df43257abd002a77c5792f02cff4ef0ee5add504533a9d8cbR71-R72) and transformed into one merged associative array like so:

[
  'project' => [
    'title' => '...',
  ]
]

This doc is useful if you want to learn more about this processing: https://symfony.com/doc/current/components/config/definition.html

Finally, you can use <extension class="phpDocumentor\Guides\Code"> to determine which extension's "config tree" will be searched for. E.g. in this example, the child elements will be parsed using the CodeExtension (which does not exist yet). All elements that are in the root of the document and are not <extension> are parsed using the GuidesExtension (to make it easier to configure the built-in config).

[linawolf]

@wouterj, I updated the integration test accordingly, unfortunate it does not seem to work

[greg0ire]

@linawolf it looks like this is the first time a guides.xml file is created in a test. The only place where guides.xml is referenced is here:

guides/packages/guides-cli/bin/guides

Lines 33 to 35 in a824e13

	if (is_file(getcwd().'/guides.xml')) {
	$containerFactory->addConfigFile('guides.xml');
	}

but the CLI does not get run when in tests, right? So I don't think the guides.xml in this PR will be taken into account at all.

[linawolf]

@greg0ire so I am loading the guides.xml in a test now if it is present, however it still does not seem to do anything...

[wouterj]

Fyi: I'm taking a look now

[wouterj]

Fixed the tests, added some docs, added the XML schema and did some other minor improvements to the project settings flow.

I think this is ready now.

[linawolf]

Looks good to me, thanks a lot for these changes