[TYPO3-english] Another good reason to switch to ReST

[Xavier Perseguers]

Hi Anja,

To be honest I wanted to create a news out of it, but then did not know
where to put it, on buzz.typo3.org, on typo3.org, then I should probably
do less advertisement for my extensions because they are not "official
from Core", I should search for a catchy image, ...

In the end, I simply wrote to this ML because it was much easier.

I understand your concern regarding retention, search for the info and
so on. So if someone gives me answer to my questions, I'll happily write
it down somewhere else :)

Greetings

Anja Leichsenring wrote:
> Hi Xavier,
> 
> another good reason to thank you and the whole documentation team for
> this outstanding work you accomplished.
> 
> Will the explanations and hints you give in this articles be online
> somewhere for reference? You know, Mailing list stuff is hard to find
> when you need it.
> 
> Greetings Anja
> 
> On 08/03/2013 02:32 PM, Xavier Perseguers wrote:
>> Dear TYPO3 community,
>>
>> Here is another good reason to switch to ReST today! Our documentation
>> platform is now generating TYPO3-branded PDF automatically:
>>
>> *System Extensions*
>>
>> http://docs.typo3.org/typo3cms/extensions/css_styled_content/latest/_pdf/css_styled_content.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/dbal/latest/_pdf/dbal.pdf
>> http://docs.typo3.org/typo3cms/extensions/felogin/latest/_pdf/felogin.pdf
>> http://docs.typo3.org/typo3cms/extensions/form/latest/_pdf/form.pdf
>> http://docs.typo3.org/typo3cms/extensions/indexed_search/latest/_pdf/indexed_search.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/linkvalidator/latest/_pdf/linkvalidator.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/openid/latest/_pdf/openid.pdf
>> http://docs.typo3.org/typo3cms/extensions/recycler/latest/_pdf/recycler.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/rsaauth/latest/_pdf/rsaauth.pdf
>> http://docs.typo3.org/typo3cms/extensions/rtehtmlarea/latest/_pdf/rtehtmlarea.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/saltedpasswords/latest/_pdf/saltedpasswords.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/scheduler/latest/_pdf/scheduler.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/workspaces/latest/_pdf/workspaces.pdf
>>
>>
>> *Community Extensions*
>>
>> http://docs.typo3.org/typo3cms/extensions/image_autoresize/latest/_pdf/image_autoresize.pdf
>>
>> http://docs.typo3.org/typo3cms/extensions/news/latest/_pdf/news.pdf
>> http://docs.typo3.org/typo3cms/extensions/restdoc/latest/_pdf/restdoc.pdf
>> http://docs.typo3.org/typo3cms/extensions/sphinx/latest/_pdf/sphinx.pdf
>>
>> We are still in the process of automating the rendering for every
>> extension using ReStructuredText instead of OpenOffice and to properly
>> integrate links to docs.typo3.org within www.typo3.org/extensions.
>>
>> In the mean time, you may already rework your own extension manuals and
>> convert them to the new format.
>>
>> In order to check your new manual is as shiny as it should be, you will
>> need to install a Sphinx environment locally. Although this is not a
>> tricky task, I highly encourage you to install a TYPO3 extension of
>> mine, namely EXT:sphinx [1], because it does everything for you with a
>> single click, is compatible with Linux, Mac OS X and Windows (check
>> documentation if needed) and will install every component locally to a
>> TYPO3 website, without "polluting" your whole machine. Further more,
>> once you start willing to install and configure every tiny bits of a
>> powerful Sphinx environment (such as TypoScript highlighting) without
>> this extension you will have to do quite a lot.
>>
>> EXT:sphinx takes advantage of another extension, namely EXT:restdoc [2]
>> for a better writing experience.
>>
>>
>>
>> *How to best document your extension*
>>
>> I converted a few manuals and spent hours making them better. My
>> suggestion to be as effective as possible is as follows:
>>
>> - Use a decent text editor with ReStructuredText highlighting. PhpStorm
>> is of course perfect if you have it, otherwise TextMate on Mac OS X or
>> Notepad++ on Windows works very well. Please check dedicated page on
>> wiki.typo3.org [3] for other editors.
>>
>> - Open your documentation within EXT:sphinx's Documentation Viewer
>> (under "Help"), using layout "Interactive" (needs EXT:restdoc) and make
>> sure the checkbox "Always render documentation" on top right is checked
>>
>> - Navigate to the chapter you are currently working on, each time you
>> click the "OK" button in the toolbar, your documentation will be
>> recompiled and your current chapter will be reloaded (thus the
>> usefulness of layout "interactive" over "static")
>>
>> - If you want to check PDF output, you will have to install LaTeX,
>> please read the EXT:sphinx documentation, this is straightforward.
>> Compiling to PDF is then just a matter of switching to layout "PDF".
>>
>>
>>
>> *How to start*
>>
>> - If you have an OpenOffice manual, either use Git master branch of
>> EXT:sphinx (as of today) to have a wizard to convert your documentation
>> (see [4] for a demo) or convert it as explained on [5]
>>
>> - If you don't have any manual for your extension, either use Git master
>> branch of EXT:sphinx (again) to have a wizard to kickstart a new
>> documentation or use version from TER, kickstart a documentation project
>> somewhere in fileadmin/ and move it to your extension, within directory
>> Documentation/
>>
>>
>>
>> *I'm not an extension author, can I create a custom documentation?*
>>
>> Of course! And TYPO3 6.2 LTS is already featuring a documentation module
>> in Backend (see demo on [6]). Check it out today using TYPO3 git
>> repository. As an individual or an agency, you will be able to show your
>> own documentation to your clients. Read technical details on [7].
>>
>>
>>
>> *When will my manual be rendered on docs.typo3.org?*
>>
>> We are all working hard to make that available ASAP. Chances are it will
>> be ready by the time you will have converted your extension manual to
>> ReST (and went over the automatic conversion to fix little conversion
>> bugs of course, just give us a few hours more :D)
>>
>> Do not hesitate to contact me (through ML or Twitter @xperseguers, no
>> mail please) or any member of the Documentation team (they have a
>> dedicated mailing list, don't be shy, join!).
>>
>> Happy documenting!
>>
>>
>> [1] http://typo3.org/extensions/repository/view/sphinx
>> [2] http://typo3.org/extensions/repository/view/restdoc
>> [3] http://wiki.typo3.org/Editors_%28reST%29
>> [4] http://www.youtube.com/watch?v=MSXG9bqQZxM
>> [5]
>> http://docs.typo3.org/typo3cms/extensions/sphinx/UserManual/SphinxRest/Index.html
>>
>> [6] http://www.youtube.com/watch?v=n0drBeKHfrc
>> [7] http://docs.typo3.org/typo3cms/extensions/documentation/
>>
> 

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

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