[TYPO3-doc] New: Use a YAML file "Settings.yml" for configuration in your ReST documentation

Wed Aug 15 09:56:02 CEST 2012

New feature
===========

I've implemented a new feature yesterday that enhances the
capabilities of Sphinx for our TYPO3 ReST documentation projects.

Sphinx is the tool that takes our ReST files as input and builds HTML
or PDF or whatever on output. A standard Sphinx project uses a
'conf.py' file for configuration of the build process. Unfortunately
this ((ansatz)) has some drawbacks. One is that it's potentially
dangerous executable code. And another on is that it may contain
machine specific technical settings that a normal editor shouldn't be
bothered with. So we were looking for a better solution. It is now
available. And here is how it works:

We have agreed on that your documentation starts somewhere in a folder
"Documentation" with the master document "Index.rst". You may now add
a project specific 'Settings.yml' file that is versioned all along
with the project. It goes to the folder where your master document
resides. This is step 1: Add a Settings.yml file:

Step 1
------

  SomePackage.git/
  |- Documentation/
     |- Index.rst
     |- Settings.yml

Step 2 (optional)
-----------------

You only need to do step 2 if you're rendering ReST projects locally
for yourself. Then please add a TYPO3 specific codeblock manually to
the end of your 'conf.py'. You can grab the codeblock from [1]

Step 3 (optional)
-----------------

You only need to do step 3 if you're rendering ReST projects locally
for yourself. This means that you have Python, Docutils, Sphinx and so
on installed on your machine as described in [2]. I would encourage
you to do so.

  1. Get a snapshot of [3]
  2. Go to folder 'ExtendingSphinxForTYPO3' on the command line
  3. Run ``python setup.py install`` or 
     ``sudo python setup.py install``. This will add a package
     't3sphinx' to your Python interpreter.

Verify that the package is properly installed and find out where your
files reside:

  C:\Users\marble>python
  Python 2.7.3 (default, Apr 10 2012, 23:31:26) [MSC v.1500 ...] 
  Type "help", "copyright", "credits" or "license" for ... information
  >>> import t3sphinx
  >>> dir(t3sphinx)
  ['__builtins__', '__doc__', '__file__', '__name__', 
   '__package__',   '__path__', '__version__', 'os', 'package_dir',
   'pathToGlobalYamlSettings', typo3_codeblock_for_conf_py',
   'yamlsettings']
  >>> t3sphinx.pathToGlobalYamlSettings

'D:\\Python27\\lib\\site-packages\\t3sphinx\\settings\\GlobalSettings.yml'
  >>> t3sphinx.typo3_codeblock_for_conf_py

'D:\\Python27\\lib\\site-packages\\t3sphinx\\resources\\typo3_codeblock_for_conf.py'
  >>> exit()

  C:\Users\marble>

How it works
============

During the Sphinx build process the Python configuration file
'conf.py' is executed. Variables defined there are 'conf.py' module
variables and influence the build process. With the above
modifications we will also create several Yaml files for instructional
and diagnostic purposes. This is what happens:

  1. Sphinx proceeds normally and prepares the variables in 'conf.py'.

  2. We take those current settings of 'conf.py' and dump them as file
     '10_conf_py.yml' in the directory that we have chosen for
     logging. See [4] for such a folder on the server or
     ``Documentation/_make/_not_versioned/`` in your local project.

  3. Following ``t3sphinx.pathToGlobalYamlSettings`` we try to find a
     global Yaml file 'GlobalSettings.yml'. This is meant to exist
     only once on a machine and should be maintained by the 
     TYPO3 Docteam.

  4. We read the 'GlobalSettings.yml' file and dump what we have
     parsed from Yaml to '20_GlobalSettings.yml' in our logging
     directory.

  5. We override values in 'conf.py' with those found in our global
     settings file. If values existed they are replaced completely.
     This means: there is *no* deep replacement. Instead variables
     are replaced completely at the top level.

  7. We dump the now current 'conf.py' to ``10_20_conf_py.yml``
     in our logging directory.

  8. We try to find and read the project specific
     ``Documentation/Settings.yml`` file.

  9. We dump what we have parsed from Yaml to '30_Settings.yml'
     in our logging directory.

  10. We override values in 'conf.py' with those now found in our
      global prject specific settings file 'Settings.yml'. 

      If values existed they are replaced completely.
      This means: there is *no* deep replacement. Instead variables
      are replaced or created completely at the top level.

  11. We dump the now current 'conf.py' to ``10_20_30_conf_py.yml``
      in our logging directory.

      ``10_20_30_conf_py.yml`` shows the **final settings** that
      are actually being used in the Sphinx build process.

In short this means:
====================

- You now may use a ``Documentation/Settings.yml`` file to
  selectively define values you otherwise would have written
  directly in ``conf.py`` file.

- You only need to specify values you want to be different.

- Watch the logging directory [4] or [6] for instructional and 
  "diagnostic" Yaml files that tell you what has happened and what can
  be done how.

Finally
=======

For question please ask here or in [5].
For feature requests or bug reports create an issure on [5].

Thanks for your attention - and keep the flow!

Martin

[1]
http://git.typo3.org/Documentation/RestTools.git?a=blob;f=ExtendingSphinxForTYPO3/src/t3sphinx/resources/typo3_codeblock_for_conf.py;hb=master
[2] http://wiki.typo3.org/Rest (-> Installation)
[3] http://git.typo3.org/Documentation/RestTools.git
[4] as existing example:
http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Example/OfficialManual.git.make/
[5] https://forge.typo3.org/projects/tools-rest
[6] local logging directory: Documentation/_make/_not_versioned/

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de