Sensible defaults for picking destination URLs

[mvriel]

In phpDocumentor3, we have done work to support multiple versions and documentation sets. This means that, shortly, you could generate documentation for every version of your project and even split this per component and/or generate both API documentation and 'regular' documentation.

To support this new scheme and provide backwards compatibility with how phpDocumentor 2 generated documentation we introduce a series of sensible defaults. For which I will describe the rules here that are to be implemented.

There are 3 levels where you can define output paths in the new configuration:

1. Top-level, this is the root path where the output is generated
2. Version-level (folder), this is the subfolder for a specific version of your project
3. Documentation set-level (output), this is the subfolder, within the version, where a set of documentation (API, Guide, etc) will be rendered to.

Currently, we assume that assets (CSS, JS, etc) are copied into the root path of the output and is shared between all versions and documentation sets.

We define the following scenarios:

	Nr. versions	Version has folder	Nr. documentation sets	Set has output	Expected outcome
!	1	no	1	no	Generate docs in the top-level root path to match the behaviour of phpDocumentor 2. This should also be 'the default' of the application when no options or command-line arguments are provided that change this behaviour
!	any	any	1 API + 1 Guide	no	Guide documentation is generated in the root of the version (when provided; otherwise the root folder itself), i.e. /3.0.0/, and the API set is generated in the subfolder api in the root of the version (when provided; otherwise the root folder itself), i.e. /3.0.0/api/; this is the expected default when Guide generation lands in phpDocumentor and users provide both a guide location and a source location.
	1 or more	yes	1	no	Generate docs in the version's subfolder of the root path
	1 or more	yes	1 or more	yes	Generate docs in set's output folder, in the version's subfolder, of the root path
	2 or more	no	1	no	Generate docs in a subfolder of the root path named as the version number, i.e. /3.0.0/
	2 or more	no	1	yes	Generate docs in set's output folder, in a subfolder of the root path named as the version number, i.e. /3.0.0/api/
	any	any	other	no	Error - we do not dare make assumptions on what a project would prefer as a folder structure for their generated documentation.

[mvriel]

@jaapio can you check this matrix if I missed anything and that this matches what we discussed?

[jaapio]

Related to #2159

I think the situation described in #2159 is missing here. We can have multiple API's in a single documentation set. Either #2159 is invalid which is plausible in the light of this item.