[TYPO3-doc] Intersphinx keys

[François Suter]

Hi Martin,

> we'll have the documentation team meeting this evening and everybody
> is somehow busily preparing something - so I don't want to stand back.

;-)

> I've just done some experiments with this. I would like to propose to
> introduce a configuration file 'Settings.yml' in YAML format [] that
> IS OPTIONAL.
>
> If present it should be valid YAML and it should be in the root folder
> of the documentation project. For example:
> .../Tca.git/Documentation/Settings.yml
>
> It belongs to the documentation, it is versioned and it is meant to be
> maintained by the editors of THAT documentation project.

This sounds good. I prefer this solution to the conf.py file.

>    intersphinx_mapping:

Now we just need to agree about the keys. I'm not entirely happy with 
some of the changes you propose.

>      # t3eme      :
> ['http://preview.docs.typo3.org/TYPO3/ExtensionManualExample/', null]

We don't need that one. I wouldn't expect anybody to cross-link to the 
example manual.

>      # t3extbasebook: ['', null]

OK, why not.

>      # t3gs       :
> ['http://preview.docs.typo3.org/TYPO3/GettingStartedTutorial/', null]

That really does not look IMO. Maybe "t3start"?

>      # t3isr      :
> ['http://preview.docs.typo3.org/TYPO3/IndexedSearchReference/', null]

Actually this will not be a Core manual once we complete the migration. 
It should go back to being a system extension manual. And "isr" is 
really not explicit enough anyway.

> The idea is that we have "Settings.yml" to place ANY settings or
> comments that may be needed and to reserve the key 'conf.py' to the
> settings that usually are in the 'conf.py' file.
>
> I would use the settings in 'Settings.yml' only to OVERRIDE the
> settings of my serverside nonversioned 'conf.py'.

As said above, that sounds good to me. I still regret that we can't use 
information like author and such straight from the ReST, but it seems 
like we have no choice. At least have an explicit YAML file, part of the 
project, makes it less likely that people will forget to update 
duplicate data.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch