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

[Xavier Perseguers]

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