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

[Christian Weiske]

Hi all,


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

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.

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?

-- 
Regards/Mit freundlichen Grüßen
Christian Weiske

-= Geeking around in the name of science since 1982 =-