[TYPO3-doc] Settings.yml // Wiki on Forge for "Documentation rendering"

[Martin Bless]

Good morning,

I'm mainly asking the Docteam members and addicts.

============
Settings.yml
============

Yesterday I layed the technical (code-) basis to implement the feature
that a './Documentation/Settings.yml' configuration file can be used.

In fact this is what I plan. In the course of rendering a Sphinx
manual this should happen:


1. conf.py
This is the typical Sphinx-style configuration. This file is
maintained by the server administrators. It is out of reach of any
editor.

1.1.
Sphinx will read 'conf.py'

1.2.
Sphinx will write a YAML file
'temp_configuration_10_system_settings.yml' into a log directory for
inspection by anyone.



2. GlobalSettings.yml
Common settings for ALL TYPO3 doc projects
This file should reside in a public Git repository under control of
the DocTeam. It is maintained using the normal Git/Gerrit workflow.
Everybody can contribute.

2.1.
Sphinx will read 'GlobalSettings.yml'

2.2.
Sphinx will a YAML file 'temp_configuration_20_global_settings.yml'
into a log directory for inspection by anyone.



3. ./Documentation/Settings.yml
Project specific settings
This file belongs to the specific doc project. It is maintain by the
projects editors and versioned along with the documentation sources
itselves.

3.1.
Sphinx will read './Documentation/Settings.yml'

3.2.
Sphinx will write a YAML file
'temp_configuration_30_specific_settings.yml' into a log directory for
inspection by anyone.


4.
Sphinx will then create a dictionary (=associative array) 'effective
settings' (ES) which will effectively be used for the rendering.

4.1 Set ES to (1.1) initially
4.2 Add all key-value-pairs from (2.1) to ES. Replace existing ones.
4.3 Add all key-value-pairs from (3.1) to ES. Replace existing ones.

4.4 Write a YAML file 'temp_configuration_90_effective_settings.yml'
into a log directory for inspection by anyone.


If you wonder how all of this would look like: I tried it as an
example here:
http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Reference/Tca.git.make/




===========================================
Wiki on Forge for "Documentation rendering"
===========================================

Actually there is much more to be considered than explained in the
above chapter 'Settings.yml'. Its only an example. So I'm looking for
a good place to compile these considerations and make them available
to the public.

I would like to have a sub project of "Documentation" on Forge named
"Documentation rendering" (parallel to api.typo3.org, ...,
wiki.typo3.org). It should have the Wiki turned on. And it should be
open for writing for all those involved in the process of setting up
the documentation server.

And I would love to see Fabien writing there as well.

What do you think?

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de