[TYPO3-doc] Meta data in conf.py

[Martin Bless]

[François Suter] wrote & schrieb:

>Hi,
>
>I'm opening a separate thread to make things a bit easier to follow.
>
>The conf.py file that is necessary for the rendering of a reST manual 
>with Sphinx contains metadata about the manual. Now some information 
>like title, author, version, date, etc., are already in the reST file(s).
>
>Is there a way to avoid that duplication? Or did I misunderstand something?

I'm slowly approaching an opinion about that. I don't forsee actually
what values in the conf.py is do what and will be necessary in the
future.

The main problem probably is that bibliographic data inside the
document may be different from the (more restricted?!) one used for a
special output format.

We could fetch the bibliographic data out of the document. But to do
that in a really clean way its rather expensive and would mean: Parse
the ReST document to get the internal structure and run a Docinfo
renderer for that. See these examples: 
http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Reference/CodingGuidelines.git/Documentation/Index.pseudo-xml.txt
http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Reference/CodingGuidelines.git/Documentation/Index.xml

Formally the docinfos a key value pairs. But one field_name "created"
can have multiple "field_body"s of unlimeted complexity.

We /could/ define restrictions for bibliographic data by conventions
and social control. But that may lead to unnecessary restrictions,
will lead to many disputes and consumes manpower, as the tool that
fetches the data out of the ReST document needs to adapt to the
discussion and maybe changing demands. Biggest disadvantage: These
kind of restrictions would always be intransarent, that is, not
obvious.

On the other hand I've made the experience that people don't have
problems at with writing some more lines if only they understand what
they are doing.

The more I think about it I like the idea with the Yaml file. Like

Package/
|-- Documentation/
    |-- Index.rst
    |-- config.yml

I had mainly the official docs on my mind up to now. But, François, if
you feel like let's start with the "one and only right structure"
right away everywhere, then its better to decide now.

Because /with/ the config.yml file this would be the actual starting
point of the whole documentation project, as it may for example define
that the "master_doc" is 'index' and not 'Index'.

My 2 cents.

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de