[TYPO3-doc] Create custom inline markup reStructuredText

[Fabien Udriot]

Hi,

How to add custom inline markup / role? I took the time to dig into the topic for the needs of the 
Extbase translation book. One of my interrogation was whether an extension could easily be shipped 
and deployed on third system. The answer is yes!

To add custom roles there are two approaches:

1. Use the intern mechanism provided by Sphinx.
    *Pro*: very straight forward - no programming involved

.. role:: foo

:foo:`This is bar text`


2. Extend reST by adding a new extension
    *Pro*: can be processed at a low level and be possibly enriched for generating link or
    whatever stuff...


How to
------

* In file "conf.py" add the following lines

sys.path.append(os.path.abspath('ext/foo/'))
extensions =['foo']

Example: 
https://svn.typo3.org/TYPO3v4/Documentation/book_extbase_fluid/trunk/Documentation/_config/ext/method/

* Write your extension in directory "ext" as demoed in
https://svn.typo3.org/TYPO3v4/Documentation/book_extbase_fluid/trunk/Documentation/_config/ext/method/

That's it! Then, you are able to write in your source file:

:foo:`This is bar text`

The difference of the two approaches resides on the HTML that is going to be outputted. The first 
one will wrap your text within a <span class="foo">my text</span>. The second one, would be up to 
you (means: what you have decided to do...)

Hope it can help..

Fabien

Ps. I am just putting some of the questions / answers, I asked myself while diving into reST.


What is the difference btw Sphinx and Docutils?
++++++++++++++++++++++++++++++++++++++++++++++++

Sphinx is built on Docutils, a set of tools for parsing and working with reStructuredText markup.

What is called a Directive?
+++++++++++++++++++++++++++

Directives let you work with large blocks of text and intercept the parsing as well as formatting 
steps. Example:

::

     myCode comes here
     and here

What is a Role?
++++++++++++++++

Roles are intended for inline markup, within a paragraph. Example:

My paragraph contains a :strong:`a role`


On my machine - Mac OS - where is the source code being stored? (Sphinx + Docutils)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

/Library/Python/2.6/site-packages/docutils-0.8.1-py2.6.egg
/Library/Python/2.6/site-packages/Sphinx-1.0.7-py2.6.egg




On 10/13/11 4:26 PM, François Suter wrote:
> Hi Fabien,
>
>>> perhaps this helps a bit::
>>> http://www.doughellmann.com/articles/how-tos/sphinx-custom-roles/
>>
>> Good hint! Thanks. It matches what we need, I think
>>
>> Yet another resource:
>> http://docutils.sourceforge.net/docs/howto/rst-roles.html
>>
>> However, I haven't figure it out yet where to put the code precisely.
>> Some mentions "docutils". Couldn't it be stored within the folder
>> hierarchy so that it could easily be shipped for third party? I haven't
>> dug much into that yet...
>>
>>> I think in Sphinx and reStructuredText terms its text 'roles' that we
>>> need to add.
>>
>> Yes.
>
> We will indeed need such custom markup, in particular for TypoScript reference as you mention. So
> your explorations will be very useful. Please document your findings in the wiki. I guess it's worth
> creating a new page and relating it to the reST category (http://wiki.typo3.org/Category:ReST).
>
> Thanks!
>