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

Wed Aug 15 12:45:25 CEST 2012

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Awesome!

Kind regards
Steffen

- -- 
Steffen Gebert
TYPO3 v4 Core Team Member
TYPO3 Server Administration Team Member

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

I work for TYPO3 solely in my spare time. If you think that
my work helps you running your business, you are invited to
send me a donation via PayPal to this email address. Thanks

Am 8/15/12 9:56 AM, schrieb Martin Bless:
> 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:
> 
> Microsoft Windows [Version 6.1.7601] Copyright (c) 2009 Microsoft
> Corporation. Alle Rechte vorbehalten.
> 
> 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/
> 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.18 (Darwin)
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJQK33FAAoJEIskG/rSlyw4rfEH/i5licqot+mEydC2U3AckTzy
C4lNLLew89Vh2nTQSXMRIlRzqpMJxBmAUGEa8eyl9beoltcI7/Xvp9yVmPQ0L8Cg
2gxRWamtXUFsJiZMU1GzVpVEVtPVK0As/lcCPZsmEEslyyPB1ScuNExb19Qnddfk
ZzX8vIwf+hYgzkjPDQcQCOwzqvoxkkx4pl/U1e1xf5hqAsfBTwLYEWOHMquyRNMc
7k0ABZlVK58KPt+/C7hXx2z+M9kY994OUwU30E3+IIJYBUTa18WH3MMrUKrE19yL
rAvp0ccSMV7cFwdZvYDgF9B8nlgpWCvmYTHRY7t255olxSyyeKkNtEVcJjrkqUQ=
=I8pO
-----END PGP SIGNATURE-----