Background

TYPO3/Fluid ViewHelpers include description and simple code snippets in the comments

Example: https://github.com/TYPO3/Fluid/blob/master/src/ViewHelpers/AliasViewHelper.php

This can and is used to generate documentation, for example https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/typo3fluid/fluid/latest/Cache/Disable.html

Problem

Currently, Markdown specific markup is used
Current description and code snippets in comments of TYPO3/Fluid are not rendered correctly by TYPO3 ViewHelper reference (because Markdown is used and reStructuredText expected)
ViewHelpers in both projects TYPO3 CMS and TYPO3/Fluid use diffent formatting in the description and code blocks in the comments
Additional markup, such as <code> in TYPO3/Fluid project or .. note:: in TYPO3 project make the text more difficult to read in plain text (e.g. when viewing in IDE)

Goal

I propose to use a simplified markup that will be correctly rendered by both reStructuredText and Markdown engines and that is also well readable as text.

Additionally, only a minimal set of markup should be used (as is currently already the case).

The idea is based on the gist "Markdown and reStructuredText": https://gist.github.com/dupuy/1855764

Here, I focus only on what is necessary for the ViewHelper documentation and ignore all that is not necessary and should not be used, such as links. The goal is to keep the text as text-based as possible with minimal formatting, but of course code blocks should stand out and syntax highlighting be used when rendered (if possible).

The common subset

Code blocks

should be indented 4 spaces
for reST they must be preceded with double-colon ::

This is an example::

    <f:blank/>

Inline code

do not

use the textroles as in :xml:

use double backticks (double or single backticks would both be ok for Markdown or reST. Double backticks are often used in Markdown if the inline code itself contains a `. Both would be fine in this case.

Example:

 As you cannot use ``<f:random>`` in ...

Headers

Do not use #, ## to precede headers
Do not use = header = either
Use underlines
The hierarchy is automatically determined by which underline is used first, next etc.
Stick to the correct underline style
Preferably, use only one (or max. 2) underline level and use this sparingly
Alternatively, bold can be used to mark text

First level
===========
    
Second level
------------

Bold

Bold text is directly preceded and followed by 2 asterisk: **this is bold text**

Lists

Must be preceded and followed by a blank line

This is a list:

* item 1
* item 2

More text

Example

This example can be used to view the code online on GitHub and render it locally with the TYPO3 CMS docs rendering toolchain:

https://github.com/sypets/RstMarkdownExample

Possible problems

So far, no actual problems.

sypets/MinimalSubsetOfMarkupForFluidTypo3ViewHelpers.md