[TYPO3-doc] NEW: Automatic listing of crossreferencing targets works!

[Martin Bless]

SUMMARY:

Ha, cool stuff: My first Sphinx extension seems to work. It brings
to you a new directive which inserts a list of referencing
targets:

  .. ref-targets-list::

If you insert that samewhere in your ReST source it will insert a
list of all targets in you document.

As an example:

See this source [1]:
http://preview.docs.typo3.org/TYPO3/TyposcriptReference/_sources/Targets.txt

and see this result [2]:
http://preview.docs.typo3.org/TYPO3/TyposcriptReference/Targets.html

Not bad, I would say ;-)))


MORE DETAILS FOR wReSTlers:

What is it good for?

Let's say you're writing your own ReST document and 't3sphinx' is
installed or it's going to be rendered on the server. Now, when
you whant to linke to the TEXT content object in the
TyposcriptReference you don't have to care about URLs and where
that link actually is. Use the Intersphinx crossreferencing
notation instead:

(a) :ref:`t3tsref:cobj-text`
(b) :ref:`The content object TEXT <t3tsref:cobj-text>`

Both (a) and (b) should automatically link to
http://preview.docs.typo3.org/TYPO3/TyposcriptReference/ContentObjects/Text/Index.html#cobj-text

YOU don't have to change anything when the documentation will be
moved to another place.

With (a) the linktext schow will be the text that is defined in
the target document ("TEXT" at the moment). 

With (b) you define the linktext yourself.

This means that if you want to make those permanent references,
and you surely will want them, you need to know what link targets
the editors of the TyposcriptReference have defined. With the new
directive the editors can easily let you know as you see on [2].

If you wonder what that 't3tsref' means: It's the short name for
the TyposcriptReference we have agreed on. It's part of the so
called "Intersphinx Mapping" which describes a relationship
between shortnames and URLs.

The current Intersphinx mapping is defined in GlobalSettings.yml
and looks like this:

---
conf.py:
  intersphinx_mapping:
    t3admin:
    - http://preview.docs.typo3.org/TYPO3/AdministratorsGuide
    - null
    t3api:
    - http://preview.docs.typo3.org/TYPO3/CoreApiReference
    - null
    t3cgl:
    -
http://preview.docs.typo3.org/TYPO3/CodingGuidelinesReference
    - null
    t3editors:
    - http://preview.docs.typo3.org/TYPO3/EditorsTutorial
    - null
    t3fal:
    -
http://preview.docs.typo3.org/TYPO3/FileAbstractionLayerReference
    - null
    t3inside:
    - http://preview.docs.typo3.org/TYPO3/InsideTypo3Reference
    - null
    t3install:
    - http://preview.docs.typo3.org/TYPO3/InstallationGuide
    - null
    t3l10n:
    -
http://preview.docs.typo3.org/TYPO3/FrontendLocalizationGuide
    - null
    t3security:
    - http://preview.docs.typo3.org/TYPO3/SecurityGuide
    - null
    t3services:
    - http://preview.docs.typo3.org/TYPO3/Typo3ServicesReference
    - null
    t3skinning:
    - http://preview.docs.typo3.org/TYPO3/SkinningReference/
    - null
    t3start:
    - http://preview.docs.typo3.org/TYPO3/GettingStartedTutorial
    - null
    t3tca:
    - http://preview.docs.typo3.org/TYPO3/TCA-Reference
    - null
    t3ts45:
    -
http://preview.docs.typo3.org/TYPO3/TyposcriptIn45MinutesTutorial
    - null
    t3tsconfig:
    - http://preview.docs.typo3.org/TYPO3/TSconfigReference
    - null
    t3tsref:
    - http://preview.docs.typo3.org/TYPO3/TyposcriptReference
    - null
    t3tssyntax:
    -
http://preview.docs.typo3.org/TYPO3/TyposcriptSyntaxReference
    - null


Alright then, it's time for lunch!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de