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

[Martin Bless]

Hi Christian,

>I'm facing the dilemma now that having a README

I understand. Please let's try the following:

- use that ./README.rst at the toplevel
- place an additional Yaml file  ./Settings.yml there
- you can copy that from some other project like [1]
- fill in copyright, project and version which is good anyway as
it appears on docs.typo3.org
- if you write
  Rendered |today|
  somewhere in you README.rst that will show the actual date and
time of the last rendering on docs.typo3.org. And elsewhere it
doesn't hurt very much.

Further:
- At [2] "Files in the build folder" there's a bit of explanation
about those Yaml files
- With that knowledge you can check [3] There you have the
effective settings of the rendering of your "contexts" extension.

- master_doc: Index 
  is the interesting one. It tells Sphinx that Index.rst in the
Documentation start folder is the master document that starts this
documentation project. Note the there is a "source_suffix: .rst"
setting as well.

- In your cut that line "master_doc: Index" and paste it to your
Settings.yml. Then change it to "master_doc: README" That would
tell Sphinx to look for "README.rst" as master document.

- When you look at the first line of [4] you see what I've entered
as startdir for Documentation. I'll drop the "/Documentation" at
the end and it should work.

Make a noise when that Settings.yml is there!


[1]
https://github.com/marble/typo3-documentation-starter/blob/master/Documentation/Settings.yml
[2]
http://docs.typo3.org/typo3cms/Index.html#trigger-documentation-rendering
[3]
http://docs.typo3.org/typo3cms/extensions/contexts/latest/_make/10+20+30_conf_py.yml
[4]
http://docs.typo3.org/typo3cms/extensions/contexts/latest/_make/Makefile

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de