[TYPO3-doc] Textrole :api:`something`to link to the TYPO3 api

[François Suter]

Hi Martin,

> I heard about the need to have a textrole 'api' that helps linking to
> our api resources.

Yes, that would be very useful.

> Now, with API it's a bit more complicated since we have different API
> destination websites and they may change more soon than later.

Yep, that doesn't seem simple.

> Request:
> What I need to program that logic is a list of samples of the various
> API links. For each I need a triple a/b/c:
>
> a: What do you write in ReST?
>     What is 'content' when you write:  :api:`content` ?
>
> b: What should appear as linked text?
>
> c: What is the desired url pointing to the API?

What I would expect is to be able to use a class name, that name would 
be used as the link text and the link would point to the proper page on 
api.typo3.org.

Now that doesn't seem simple at all. Let's consider something like:

:api:`t3lib_div`

The text would be: "t3lib_div" and the link: 
http://typo3.org/api/typo3/classt3lib__div.html

The link points to the current stable release of TYPO3. The problem is 
that we have different TYPO3 versions available, plus API for Extbase, 
FLOW3 and Fluid. Probably more in the future. So we probably need some 
extra keyword, like:

:api:`typo3/t3lib_div` or :api:`typo3:t3lib_div`

for example, indicating that this is a TYPO3 reference. The text would 
still be only "t3lib_div".

Now it seems to get more complicated with the current master and 
namespaces. For example, the CMS backend controller class is

\TYPO3\CMS\Backend\Controller\BackendController

To refer to it unambiguously in the documentation, we probably need to 
write this fully qualified class name instead of just 
"BackendController". So the ReST code would be:

:api:`\TYPO3\CMS\Backend\Controller\BackendController`

(key to point to the right API not included)

and the expected URL is:

http://api.typo3.org/typo3v4/master/html/class_t_y_p_o3_1_1_c_m_s_1_1_backend_1_1_controller_1_1_backend_controller.html

It would be interesting if Fabien could tell us what are the exact rules 
Doxygen uses for assembling the URLs.

To add to that, the FLOW3 API follows a totally different structure for 
URLs:

http://api.typo3.org/flow3/master/TYPO3/FLOW3/Persistence/Generic/class-PersistenceManager.html

So either we manage to have some single logic or we would need to 
actually have several roles to differentiate the handling.

This topic may be more complex than anticipated.

Cheers

-- 

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