[TYPO3-doc] RFC: Request rendering through web service

[Martin Bless]

Hi Karsten,

((btw: find me on skype "martin.bless" or Google hangout
"martin.bless at gmail.com"))


>I am working on TYPO3.Docs right now, and the next step would be the possibility to request rendering of documentation via a web service.

Current state of notification services:


A. TYPO3 Git/Gerrit

Here [1] is a copy of a PHP script that is called when a "change
merged" event happens at git.typo3.org. It does a POST request and
transmits an array via JSON - very much as you proposed. The data
transmitted looks like this [2]. Note that you can look around
there [3]. Receiver of a notification request from [1] is [4].


[1] http://docs.typo3.org/php/git-hook-change-merged/
[2] http://docs.typo3.org/php/zzzlog-1.txt
[3] http://docs.typo3.org/php/
[4] http://docs.typo3.org/php/git-typo3-org-change-merged.php


B. TER

Thomas Löffler is planning to implement a similar notification
service as in A. at "The typo3.org project":
http://forge.typo3.org/issues/48476


C. Github

People with documentation projects at Github can add an
WebHook URL at Github as shown in [5]. A push to Github will then
invoke a POST request with a JSON array similar to [6]. Receptor
of that data is script [7].


[5]
http://docs.typo3.org/typo3cms/drafts/github/marble/DocumentationStarter/Quickstart/DetailsStep5.html#details-step-5
[6]
http://docs.typo3.org/typo3cms/drafts/github/marble/ManageGithubRepositories/Development/Step2.html#example-of-github-hook-data-payload
[7]
http://docs.typo3.org/services/handle_github_post_receive_hook.php


> Whatchathink?

I'm not sure I understood all of what you wrote. To say it in my
words: 
"""
We should accept and take into account that there may be a lot of
different sources of documentation in the world. Each "source"
(Gerrit, TER, Forge, github, bitbucket, ...) may have special
technique to inform our rendering machinery about updates. A
preferred way is the transmission of JSON data by a POST request.
For each source we'll probable need a specially taylored receptor
as we may not be able to influence what data is being send.
"""

Does that make sense to you?

Proposal:
I see that you're doing the development on machine srv130, which
is good as it's the machine we want to finally move to and, very
important, as it's at the moment totally independent of the srv123
machine that currently serves docs.typo3.org.

I could leave everything on srv123 as it is but additionally
forward each JSON array that arrives from

- A. TYPO3 Git/Gerrit
- B. TER
- C. Github

to an address at srv130. 

In my world there would be a dedicated receiver for each source at
http://docs.typo3.org/services/

like:
handle-change-merge-from-git-typo3-org.php
handle-github-event.php
handle-ter-event.php
and so on.

Over!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de