[TYPO3-doc] Official docs: Mostly CamelCased now (to be pushed again)

[Martin Bless]

Hi François, 

>I thought some more about this and I must say that I am really 
>disappointed to have to come to such a complex structure. I would like 
>us to brainstorm about which elements are really necessary and how they 
>could be placed inside a "package" (this being meant in a very general 
>way as either a TYPO3 extension, a documentation repo or a FLOW3 package).
>
>I found the initial situation ideal: the "Documentation" folder 
>contained just the documentation.

No problem. We can rearrange everything like that without loosing
anything. 

Proposal
========

"Package" is the general name for a bundle of files that have
documentation: an official doc, a TYPO3 extension, a FLOW3 package -
as you outlined above.

The smallest documentation project we recognize is then just one
single ReST file in a subfolder "Documentation". So that's *mandatory*
to have.

Package/
|-- Documentation/
    |-- Index.rst


Everything else is optional but follows some rules. The Package
maintainers may extended the contents of Documentation/ by any number
of ReST files, images, included files and subfolders as long as they
represent a valid Sphinx project start at Documentation/Index.rst

There is one reserved subfoldername though: "_make". This subfolder is
entrance to the experts cave:

Package/
|-- Documentation/
    |-- Index.rst
    |-- _make/   ((reserved name, optional))
        |-- ...  ((advanced stuff))


As a "proof of concept" I tried that here:
http://srv123.typo3.org/~mbless/git.typo3.org/Documentation/TYPO3/Reference/CodingGuidelines.git/Documentation/

The result is of course unchanged:
http://preview.docs.typo3.org/TYPO3/CodingGuidelinesReference/



CodingGuidelines.git
|
|-- Documentation/
    |-- .gitignore           (1)
    |-- Index.rst
    |-- MorePureDocumentation/
    |-- ...
    |-- _make/
        |-- conf.py
        |-- make.bat
        |-- make-html.bat    (2)
        |-- Makefile
        |-- build/
            |-- .gitignore   (3)
            |-- html/
            |-- json/
            |-- singlehtml/
            |-- ...
        |-- _not_versioned/
            |-- .gitignore   (4)


(1) is the usual, global .gitignore
(2) at Windows you click on that file. It will build
    build/html and start build/html/Index.html in
    the browser (if builders are installed).
(3) and
(4) exclude everything from inside the folder



Tool: RenderOfficialDocsFirsttime
=================================

As posted already I published a first release of this tool in 
http://git.typo3.org/Documentation/RestTools.git

It takes just the OpenOffice document "manual.sxw" as input and
creates the whole elaborated Documentation project structure on
output!!!

I will still have to change it so that it directly produces the new
structure with the "_make" entrance. But that's nothing severe to
change.

Input
-----

So, on the server srv123 you start with just this one file:
Package.git/Documentation/_make/_not_versioned/_genesis/manual.sxw
No other folders or files are needed.

Package.git
|-- Documentation/
    |-- _make/
        |-- _not_versioned/
            |-- _genesis/
                |-- manual.sxw
             

Output
------

As output there will be the complete Documentation project:

Package.git
|
|-- Documentation/
    |-- .gitignore
    |-- Index.rst
    |-- MorePureDocumentation/
    |-- ...
    |-- _make/
        |-- conf.py
        |-- make.bat
        |-- make-html.bat
        |-- Makefile
        |-- build/
            |-- .gitignore
        |-- _not_versioned/
            |-- .gitignore
            |-- _genesis/
                |-- manual.sxw
                |-- manual.html
                |-- manual.rst
                |-- ...
                |-- temp/
                    |-- (temporary, numbered structure) 


Cool, isn't it?

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de