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

[Anja Leichsenring]

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/
>