[TYPO3-doc] New: Use a YAML file "Settings.yml" for configuration in your ReST documentation

[Martin Bless]

[Karsten Dambekalns] wrote & schrieb:

>Hi.
>
>On 18.08.12 11:37, Martin Bless wrote:
>> It it's the nice solution you're looking for we could add that to the
>> GlobalSettings.yml. OTH I'm afraid we still have a large variety in
>> how api links are constructed. Some pages are even framed.
>
>Since there should be one machine to render API docs for all projects
>using the same tool, that problem should cease to exist.

Yes, that's very good. In the meantime I found out that it is not difficult at all (for me
;-) to create a Sphinx extension that does some specialized processing for a TYPO3
specific textrole 'api'. It could recognize the relpaths of the API links and react on
that. So it could produce different URLs. Examples::

  :api:`` -> http://api.typo3.org/  
        as http://typo3.org/api/ gives a 404 error

  :api:`typo3v4/46/html/annotated.html` ->
        http://api.typo3.org/typo3v4/46/html/annotated.html

  :api:`typo3/_about_controller_8php.html` ->
        http://typo3.org/api/typo3/_about_controller_8php.html

The logic we would need can probably be derived from page http://api.typo3.org/.


**Is that the complete logic we have?:**

  Rule 1:
     direct everything that's not empty and starts with /typo3/ to
     http://typo3.org/api/typo3/...

  Rule 2:
     direct everything else to http://api.typo3.org/...



To really be able to create a solution we need a list of all of the different use cases:

  1. ReST markup
  2. destination URL
  3. caption (= linktext, =what text in HTML should carry the link?)


Invented example A:

  1: :api:`typo3/_about_controller_8php.html`
  2: http://typo3.org/api/typo3/_about_controller_8php.html
  3: typo3/3/_about_controller_8php


Over!

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de