[TYPO3-doc] README.rst vs. Documentation/Index.rst

[Xavier Perseguers]

Hi Christian,

> You probably have seen a README file in the root directory of about any
> source code package.
> 
> Github and other code browsers already render them to show it on the
> project main page.

:-)

> Now TYPO3 decided not to use a README.rst file but to put documentation
> into Documentation/Index.rst.
> 
> I'm facing the dilemma now that having a README is (if not mandatory
> but) good behavior and automatically provides documentation in Github
> - but I cannot use it in my extension because TYPO's documentation
> generator does not look at that place.
> 
> There would be several technical solutions:
> 
> 1. Symlink Documentation/Index.rst to README.rst
>    This breaks relative links in the file (e.g. images)
> 
> 2. Include ../README.rst from Documentation/Index.rst
>    This does at least not work with the sphinx TYOP3 extension,
>    probably because including files from parent directories is disabled
>    for security reasons

I guess you refer to EXT:sphinx, I must say I did not test this use case
but inclusion should work, at least I did not restrict anything in my
extension. What I did however is restricting access to ../ relative to
documentation root when you use EXT:restdoc (and thus "Interactive"
layout in EXT:sphinx's Backend Documentation module. I will NOT remove
that security check.

> 3. Copying README.rst to Documentation/Index.rst
>    This also breaks relative links and doubles the storage space for
>    documentation
> 
> 4. Include Documentation/Index.rst from README.rst
>    At least Github doesn't render that.
>    Also, I expect some basic information in README.rst and not only a
>    link I have follow manually.

Thus you cannot simply put a link? OK, I tried on

https://github.com/xperseguers/test

and in fact it does not work. Actually, and that's the same problem with
PHP-based ReST compilers (such as Zeta Components), they can only handle
a single ReST file, not a whole "project"

> 5. Make the TYPO3 documentation generator recognize README.rst
>    This is the solution I'd prefer. Includes to Documentation/ are
>    still possible without breaking anything, and if you split your
>    manual into several rst files, you could at least have the most
>    basic information about the extension in the README.rst file
> 
> What do you say? Do you care about supporting README.rst at all?

That's the whole point, it won't support multiple files.

>From my POV, I can easily handle the case of a single README.rst file at
root with EXT:sphinx, that's trivial. As I'm already automatically
generating the _make and conf.py files to allow actual rendering, I
could generate the required "Settings.yml".

However, I'm not sure this is something that is on Martin's radar for
docs.typo3.org.

In the mean time, please open a feature request for EXT:sphinx and
advertise this extension as Github-friendly... :)

Kind regards

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org