[TYPO3-doc] Linking ReST manuals from Extensions into the TYPO3 Core

[Philipp Gampe]

Hi Benjamin,

Benjamin Mack wrote:

> Hey all,
> 
> first of all: I am highly impressed with your work and your enthusiasm
> and I am happy to see that the doc team is moving forward with ReST -
> and it really seems to be a good choice.

Thanks, the dude to really thank is Martin who did most of the work.

> Every now and then I create a new extension, and before I release it to
> the public, I want to finish the documentation for it. Well, quite a
> while ago, I stopped writing manuals in OpenOffice anymore, and started
> to write them in ReST, trying to be "in-order" with everything.

Cool.

> So this is the workflow I follow:
>  * I pick up a doc-template from git.typo3.org/Documentation/
>  * I save it in EXT:myext/Documentation/Index.rst (with images under
> Images/ and includes etc)
>  * When people want documentation for the project, I just open the
> unstyled Index.rst in the browser and read through it.

I think the example manual will be a starting point:
http://git.typo3.org/Documentation/TYPO3/Example/Manual.git?a=tree;f=Documentation

This is not final yet, but we are getting closer to what we need; e.g. this
http://git.typo3.org/Documentation/TYPO3/Reference/Tca.git?a=tree;f=Documentation
is almost ready.

I am not sure if we will support subfolders and full sphinx support for 
extension manuals, but - to my knowledge - nothing speaks against it.

> Do I miss something? Does it make sense to write a blog post to tell
> extension developers on how to do that?

I would like to wait with that until we have the tool chain ready.

We currently have a basic folder structure and a working rendering, see
http://preview.docs.typo3.org/TYPO3/

This site also contains a folder with a basic reST conversion of all TER 
extensions.

But I do not think that we currently support up extensions with reST 
documentation.
Once this is ready, there will be an announcement. But we will keep you in 
mind as early tester ;)

> So, what I'd like to have is some kind of link from the TYPO3 Core (all
> the way down to 4.5) to this unstyled file, if it exists, or to a pdf if
> the PDF file exists. My question is: What are your plans for the
> extension documentation? The idea that a PDF or HTML version is created
> every time an extension is updated in the TER? That you can trigger the
> creation from within T3?

That is the plan. We are currently looking at creating a rendering instance 
and might use FLOW3 with it's queue management for this.

> And to which rendered version should be linked in the Extension Manager?
> The latter change we could easily integrate in the Core (once we know
> and agree on what to do).

I am not sure. Best would be the HTML version with a fallback to the reST-
version if no internet connection is working.
On the HTML version should be a link to the PDF version.

Depending on how expensive the test connection to docs.t3o is, we could make 
it configurable whether to link to the HTML or PDF version.
This also depends on what happens to the extension manager and what a 
possible rewrite will support.

> PS: Is EXT:mxext/Documentation/Index.rst the right place for all new
> extension documentation?

Yes, that will be the main entry point for all documentation.

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