[TYPO3-doc] Meta data in conf.py

[François Suter]

Hi Martin,

> 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.

OK, that seems pretty ugly. Forget it.

> 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.

I agree, but let's try to avoid this as much as possible.

> 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.

I'm fine with having a Yaml file, since we seem to need some 
configuration file anyway. And FLOW3 also uses Yaml for configuration, 
so it should be known to developers.

> 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'.

I don't know if that particular example is a good idea, but I get your 
meaning.

What about Philipp's remark? Would it be possible to take the metadata 
from the Yaml file and inject it into the reST file?

That being said I would really prefer to have the bibliographical data 
in Index.rst as it makes it stand alone: someone can take that file and 
still get its context.

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?

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch