[TYPO3-doc] Reporting about the code sprint

[François Suter]

Hi again,

> I'll follow up with more technical information here.

So here we go (warning, long mail).

As mentioned in the article, the first step was to make an inventory of 
all resources used on docs.typo3.org. Martin came up with the following 
matrix:

http://docs.typo3.org/typo3cms/drafts/github/marble/DocTeamCodesprint2014/

This not only lists all the bits and pieces that make docs.typo3.org 
tick, but where to find documentation, repositories or other information 
as relevant. Some parts which were not versioned yet are now safely in 
repositories.

As you may know, we currently have two servers:

- srv123 which corresponds to http://docs.typo3.org/
- srv130 which corresponds to http://build.docs.typo3.org/

On srv130 it is the Flow application which is answering (and in 
particular package TYPO3.Docs.RenderingHub (formerly known simply as 
TYPO3.Docs)).

Both servers are not in line with one another. The Chef recipe for 
building them was not up to date with either. A very large part of the 
work done during the sprint revolved around updating and completing the 
Chef recipe used to build both servers, so that they can be identical in 
the future. Furthermore this Chef recipe is used to deliver a Vagrant 
box. This will be extremely useful for the further development of 
docs.typo3.org, as all of us can now have a fully working documentation 
server on their own computer.

The repo is here: 
https://git.typo3.org/Teams/Server/Vagrant/DocsTypo3Org.git

Setup information is in the README file.

We also discussed the current status of the Flow application, which has 
yet to be used on the production server. It should provide the following 
services:

- read the RabbitMQ queue announcing newly uploaded extensions from the 
TER (planned by the TER/T3O team).
- receive requests for rendering from other sources than RabbitMQ 
(Gerrit and Github hooks).
- provide an endpoint for explicitly requesting a rendering request 
(so-called "manual request").
- queue a rendering request (we currently have our own queue, using 
beanstalk, but we would logically switch to RabbitMQ in the future).
- send feedback after rendering, presumably to a RabbitMQ exchange (a 
thingy which posts a given message to a variety of queues, as defined by 
its configuration).
- provide a public interface which lists the currently running jobs.
- provide a restricted-access interface for managing the information 
docs.typo3.org needs for running. Also in that interface could be a 
button for triggering a rendering of all manuals.

I have made a diagram with a rough outline of the application's workflow:

https://www.lucidchart.com/publicSegments/view/534edcfc-1d5c-4592-b6e1-13e40a005bf4/image.png

Please consider it a work in progress. At least it helped us better 
visualize where we are heading.

A smaller point was the cleanup of the example manuals. It seemed 
pointless to have an example for extension manuals and one for official 
manuals, since we rarely create the latter and perfectly know how to 
build them. We don't need a specific example. Furthermore the 
information it contained about reStructuredText elements are now better 
in a primer written by Xavier:

http://docs.typo3.org/typo3cms/drafts/github/xperseguers/RstPrimer/

We reworked the extension manual example and it was promptly integrated 
into the documentation template provided by the extension_builder.

Another topic was the discussion about templating. There is a 
willingness to give docs.typo3.org its own design, in particular to make 
it more accessible to beginners. Changing templates is not an easy 
process since the site is currently made up of thousands of manuals 
(including the landing pages, which are small reST projects themselves), 
which all need to be rendered again. Furthermore the landing pages - 
being reST project - are not easy to edit, preventing regular editorial 
work.

With the current setup, there's no escaping a full rendering when 
changing the design. What we can do - though - is to settle on a 
well-known CSS/HTML framework that would make it easier to just change 
the CSS (no re-rendering needed then). We decided to head for Twitter 
Bootstrap, as it is also very useful to have for the Flow application 
(and a Sphinx theme already exists).

For editing the landing pages, it is obvious that using a CMS was the 
best solution. Although we didn't make a formal choice, it seemed rather 
obvious to go for the "modern" solution ad use Neos. This led to 
exploring if Neos could be used to drive the whole, since there already 
exists a solution to import reST rendered to JSON as Neos nodes. 
Dominique explored this quite a bit and his results are very promising.

A status can be found here: http://wiki.typo3.org/DocsTypo3OrgOnNeos

No decision has been taken yet, but this exploration was very interesting.

It is a bit hard to mention all the things that we discussed. Rest 
assured that no big decisions were taken or we would have mentioned them 
in the mailing list already.

To check all that has been achieved during the code sprint, look at the 
"Done" column in the Trello board we used: 
https://trello.com/b/tS7t57Dx/t3docs14

Feel free to ask questions.

Cheers

-- 

Francois Suter

Work: Cobweb Development Sarl - http://www.cobweb.ch

TYPO3: Help the project! - http://typo3.org/contribute/

Appreciate my work? Support me -
http://www.monpetitcoin.com/en/francois/support-me/