[TYPO3-typo3org] Integrate TYPO3 ReST documentation into typo3.org: Yes we can!

Martin Bless m.bless at gmx.de
Fri Oct 26 11:01:23 CEST 2012


Hi Tolleiv,

cool, let's go ahead. I try to pick up your questions and add my
ideas. My knowledge about the inner workings of typo3.org is about
zero right now and that of a pure frontend user only.

T3O sprint in December: It's the same with me. I'd like to do and
find out as much as possible beforehand. 

I. Technique
============

>The documentation preview looks good.

Yes, I think so. We should be able to integrate that into
typo3.org in a perfect way. My idea of *how* to do that is this.
Numbers don't mean ordering. Take this as an idea an proposal:

1. The basic idea is to make Sphinx produce HTML right away that
can be plugged into typo3.org pages without any modification. Now
that I found out to do that I'm very optimistic. I can do it.

2. Sphinx could produce this data for example:
- page title
- <div>navigation</div>
- <div>documentation=page content</div>

3. We (docteam) the Docteam create totally static HTML pages on
docs.typo3.org/TYPO3-CMS/TyposcriptRefererence. (We probably have
to think once again about the URL scheme after the renaming.)

As a preliminary example we have the structure at
http://preview.docs.typo3.org/TYPO3/

Take this as an example:
http://preview.docs.typo3.org/TYPO3/CoreApiReference/

4. This (3.) is still the old "hack of a first TYPO3 theme" of
Nov. 2011. I want to replace that with an elaborated one that
mimics exactly the appearance of typo3.org. The plan is to have
those static pages ready until 6.0 comes out.

5. The static pages shall contain the readymade HTML data of (2.):
title, navigation, content

6. We can add a canonical tag, and "noindex, nofollow" to those
statical pages.

7. To create those statical pages we don't need any individual
header content from typo3.org. It's just the other way round. See
below.

8. Concerning the styling of the new HTML constructs in the
rendered documentation I need help right as it should be adjusted
to everything else on typo3.org. I'll follow your advice and
contact Boris Hinzer about that.

9. When we have that files and folder structure on docs.typo3.org
the same structure should be present on typo3.org. So we have:

(a) http://docs.typo3.org/.../DOCUMENTATIONROOT/TheDocs/...
(b) http://typo3.org/documentation/TheDocs/...

10. The content of the pages at (b) could be generated like this:
Have a TYPO3 extensions grab the corresponding HTML from (a) using
HTTP protocol (wget, curl, ...). Cut out the HTML for naviation,
content and maybe title. Construct a normal TYPO3 page from that.
Cache and index that page at will. All links in that (sub-)
navigation and inside the HTML of the content are relative or
absolute pointing to the correct
http://typo3.org/documentation/... target. So they will work.

11. For the subtree below http://typo3.org/documentation/ we would
need special URL handling, not just "ordinary realurl".


II. Contents: *what* to show on typo3.org
=========================================

Tolliev, from former mail:

> since rendering documentation on typo3.org is only and 
> always rendering the documentation of extension-documentations
> - is my assumption right that once docs.typo3.org is ready to
> go every extension will have to provide a ReSt documentation? 

In the end typo3.org should not have to do any rendering itself.
It should only display what has been prepared on docs.typo3.org.

There may be more available on docs.typo3.org like which t3org
wouldn't need to care about:
  Manual/epub/...
  Manual/json/...
  Manual/mobilehtml/...
  Manual/singlehtml/...

In general we are changing the paradigm here: It will be the job
of t3org to display *manuals*, not extensions.

Current work of the DocTeam is much about preparing the official
documents like Tsref, CoreApi and so on to get them ready until
6.0 comes out. We'll be doing the editorial work and the styling
and rendering of the statical pages.

The official docs aren't extensions anymore anyway.

We have about 17.000 extensions with manuals in TER (including
different versions). I'm not aware of a single one that uses the
new ReST ./Documentation/... structure already. But this isn't
really a problem as we have the T3PythonDocBuilderPackage [1] for
this. It does all the processing from reading the "manual.sxw" to
generating the final HTML pages. The hope of course is that more
and more extension authors will switch to the ReST format. This
would be easy as the T3PythonDocbuilder creates exactly the
./Documentation structure from their manual.sxw. So they would
only have to download that and use it. t3org doesn't have to care
about that. We'll do that on the docs server.

You can find all those extension manuals on 
http://preview.docs.typo3.org/TYPO3/Extensions/

As you can see that "Extensions" page is kind of a "glue" page or
index page for the extension manuals. We will need content
generation for "glue" page (TYPO3 extension? Flow?)

Currently those manuals are rendered there as HTML by a special
script and an extra cron job. When the rendering machine on
docs.typo3.org works and the task queue is ready we will use the
"T3PythonDocBuilder" for those manuals as well.


III. About timelines
====================

What I find realistic:

1. Get good looking static HTML documentation pages of the
official docs ready on docs.typo3.org until 6.0 comes out. That's
where I'm asking for help with styling.

2. /If/ that "I. Technique" is feasible and someone can do the
programming on t3org they /could/ appear on t3org right away. I
can't say anything about that.

3. It may happen that PDF creation directly by Sphinx isn't ready
at that time. In that case we'll create good looking und fully
functioning PDFs from the HTML version using Acrobat.

4. Then the code sprint will help and we'll find out about further
timing then. I wouldn't be surprised if the full transition take 3
to 6 months.


III. Collecting issues for the code sprint
==========================================

- We have to find a better way to fetch the manuals from TER. I'm
using public URLs with HTTP: for this and the manual often isn't
really available at t3org.

- A TER upload should place an entry in the rendering task queue.

- ...

IV. Skype meeting
=================

It was Fabien and me who suggested to postpone the Skype meeting
until the end if this week because at that point I had no idea of
what way Sphinx could offer us. Now I have and it's outlined in
this post. So maybe we should have a meeting next week?


Code sprint:
One thing I'm not sure about what I actually can /do/ at the code
sprint. I'd like to come but if it comes to real "hacking" I'm not
sure how much I can achieve with just a Laptop. I'm very much a
"Desktop man". An alternative would be to join part time and be
remotely available at otherwise. A Skype meeting could give a
clearer picture here.


[1] T3PythonDocBuilderPackage 
http://lists.typo3.org/pipermail/typo3-project-documentation/2012-September/004099.html


Over! Let's hear what you and others think ...

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de


More information about the TYPO3-team-typo3org mailing list