[TYPO3-doc] Migration of doc_template completed (for extension developers)

[Philipp Gampe]

Hi Fabien,

Fabien Udriot wrote:
 
>> Thats why the conf.py should (or must) be included in the repository.
> 
> I am not sure about that, at least for developer extensions. The file
> contains informations that needs to be kept up to date by the developer
> that I am sure they won't be:
> 
> Example: intersphinx_mapping, version number that should stick to the
> extension. It is for me an overhead to maintain that!

That is why I proposed to have those in a submodule. Most likely they are 
always the same across all docs.

> Furthermore, in my side, I wouldn't feel confident to run any conf.py as
> it could hide harmful code... I know it is a bit paranoiac but still...
> the "make" is running as user.

conf.py is like localconf.php. So its like running the introduction package 
from T3o.
No much risk here. If we fear to have bad code in the repo, we need to 
redefine our review process.

> I am currently working on service where you could upload your doc from the
> command line and get the documentation render on demand. In that case,
> conf.py get dynamically generated. I will come back when I have something
> tangible.

Sounds cool. Mind to have a look a Xaviers version?
http://typo3.perseguers.ch/

>> The makefile should be there too, because Documentation is no default
>> folder in sphinx.
>> 
>> Also I dislike having the languages folder inside Documentation between
>> the english texts.
> 
> Ok. Waiting for your proposition about that.

Ideally, we use Poodle for translation. Have a look at what Xavier already 
found out:
http://wiki.typo3.org/Localization_(reST)

So we need kind of a service that pushes a new version to Pootle 
(http://translation.typo3.org/). Maybe Jenkins can be used for this.

Once translated, the documentation translation needs to be fetched and 
rerendered with the changed language settings.

That could be a nighly cronjob or done on demand with Jenkins.

But translations are 3. priority IMHO.

Lets first get the whole toolchain working in production, change all manuals 
to ReST ad then care about translations.

For the time being, lets leave them there, they don't hurt ;)

Cheers
-- 
Philipp Gampe – PGP-Key 0AD96065 – TYPO3 UG Bonn/Köln
Documentation – linkvalidator
TYPO3 .... inspiring people to share!