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

Tolleiv Nietsch tolleiv.nietsch at typo3.org
Sun Oct 28 21:17:59 CET 2012


Hi,

thanks, this answers quite some questions but still leaves a long 
transition path open.

For now what I read from your answer is that there's no point to 
continue any work related to the current documentation solution (e.g. to 
improve search or TER integration) because this won't live much longer 
that 3-6 months.

Most of the other things can be discussed during the sprint - URL 
migration and UI integration will be the most important one to keep 
users and google happy ;)

@Ingo - it would be great to know how we can support you to get the 
search going with the external documentation.

Cheers,
Tolleiv


Martin Bless schrieb:
> 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
>

-- 
Tolleiv Nietsch
TYPO3 Core Developer


TYPO3 .... inspiring people to share!
Get involved: typo3.org




More information about the TYPO3-team-typo3org mailing list