[TYPO3-doc] Meta data in conf.py

[Martin Bless]

Hi François,

>> But back to my original question, Martin, you didn't seem to know
>> exactly what we would use conf.py for. Can we do without it at first?
>> But it seemed be necessary for local rendering, is that true? Could a
>> generic conf.py be used?

>Martin, my question is still unanswered. Can you help me understand the 
>situation better, please?

I don't have perfect answers. So let's try to approximate.

Writing documentation should be possible without any configuration
files. Just start with a Documentation/Index.rst and starting from
that provide a valid Sphinx documentation project. That means, all
*.rst files should be referenced at least in on one .. toctree::
directive and all .. include:: references should resolve.

Information like title, author, version, date, etc. should be in the
reST file(s).

The Sphinx builder imports the configuration file "conf.py" similar to
how TYPO3 includes "localconf.php". This also means that the set of
parameters and functions that may be in there are "open end".

The Sphinx builder requires that file: See
http://sphinx.pocoo.org/config.html Those docs state:
"""
The configuration directory must contain a file named conf.py. This
file (containing Python code) is called the “build configuration file”
and contains all configuration needed to customize Sphinx input and
output behavior.
"""

I'm currently using the same conf.py for all official docs on the
server. It defines author = "Author(s)" for example and therefore in
the footer the builder writes
"© Copyright 2012, Author name(s). Created using Sphinx 1.2pre."
As an example see
http://preview.docs.typo3.org/TYPO3/TyposcriptReference/

The conf.py used on the server is not part of the Git repository. So
there's no need for a conf.py to be inside the respository.

On the other hand there exists the wish to give people an EASY
possibility to build a project at home. That's why we have
preconfigured set of files - including a conf.py - in the _make/
subdir. "Service" and "convenience" is the only reason for us to
provide the _make/ subdir. So we should consider it as optional. 

For me it makes sense to have that _make/ subdir in the officical
docs. An extension author would not have to provide it. A single
Documentation/Index.rst file as a start would be fine.

As I wrote in another posting to parse the data like author, copyright
and so on from the reST document in a perfect, canonical way would be
quite a bit of an effort.

On the other hand, to get that information using a RegExpr and a bit
of normalization wouldn't be difficult. So a function in the 'conf.py'
could retrieve that information from the Index.rst and fill it into
the conf.py. But since the editors are writing that information from
within the context of being IN the documentation they may be writing
more stuff then what's being needed in the context of generating
output with a special builder.

That's where I think an (optional) configuration file comes into play.
It should give documenters the opportunity to define certain values
used in a build by themselves. And it should be more formal to limit
variety and to make it easier to be read. Yaml, Json, Ini come into my
mind.

In other contexts it may happen that we have already "external"
configuration data that describes a manual. Extensions for example
have an extensionkey, a version number and more. I would trust that
version number more than that given in the Index.rst.

Hhm, any clarity left?

So for me it comes down to:

- one file ./Documentation/Index.rst is the smallest documentation
project

- stuff in ./Documentation/_make is an optional service we provide in
official docs

- we could implement a non perfect way to fetch meta data from the
Index.rst at the risk of getting a nonperfect result. Would be no
problem.

- we could later introduce a configuration file in Yaml or so when we
see the need. In that case it should be part of the documentation,
like ./Documentation/Settings.yml or so.

cheers ...

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de