Documentation needs as much love as the rest of the code receives. Pieces of software get only used if there is enough and well written documentation. This part of the series about TYPO3 documentation is about contributing to it. 

Edit Me on GitHub

It is very easy to contribute to TYPO3 documentation. On any official manual or guide on docs.typo3.org, there is the button “Edit me on GitHub” in the upper right corner. 

A click on this link sends you to GitHub and requires you to login. If you did not already fork the documentation repository, this is suggested directly after the login. 

If the repository is forked, you can instantly start editing the documentation. When you are ready with the improvement, you can start a pull request. This is the same procedure as with any other project on GitHub. After the pull request is submitted, the owners of the repository are notified. Your change is then reviewed and committed or you get an notice how to improve it further. The third option is that it gets declined. (Hopefully this won’t happen).

ReST Format

The official documentation format of TYPO3 and its extensions is ReST (ReStructured Text). It is often said, that it is too complicated, especially compared to MarkDown. On the one hand this might be true for simple one page documents. But when it comes to larger and more complex documents ReST has real advantages, which make it worth to dig into the syntax.

In the following chapters I will show some references and helpers, which will ease your work with .rst files and TYPO3 documentation.

References

reStructuredText Primer

The “reStructuredText Primer” is a introduction of the Sphinx project to the rst. Many other cheatsheets I found are just reflecting this document. So I would recommend to stay with this introduction: http://www.sphinx-doc.org/en/stable/rest.html (This seems to be also part of the official documentation, but at this url the formatting is much nicer ;-) )

Official ReST documentation

The rst format is defined by the Docutils project. All references and some how-tos can be found at http://docutils.sourceforge.net/rst.html. Besides the already mentioned primer, there is also a User QuickReference , which lists all basic commands to format a document.

Besides the markup ReST supports directives, which provide more functionality and advanced layouts. This part of the ReST documentation is available at http://docutils.sourceforge.net/docs/ref/rst/directives.html.

A third component of ReST are interpreted text roles. A text role can be an emphasized string, a code block or a reference to a RFC, for example. The text to which the text role will be applied is surrounded by \`. Before this text the role is mentioned and surrounded by colons : . Read more on the docutils website

TYPO3 ReST reference

For TYPO3 there is an example documentation project, which serves as some kind of stress test to all configured formats and features. It is available on docs.typo3.org. It gives a very good overview about how the various markup is rendered on docs.typo3.org.

If unsure, what is the syntax behind a certain formatting, you can spy at the end of each page: There is the link “View page source”. A click on this link reveals the original ReST markup code of this page as plain text.

I want to point out the section “This and that”. It reveals some really nice formatting, which help to render a nice and good readable documentation. Some of the shown elements elements are a sidebar, code with line numbers or special boxes.

Convert ReST to “readable” formats

The TYPO3 rst reference project shows how ReST markup is rendered on docs.typo3.org. This is the “theory” part, but it is also interesting how the self written documentation will be rendered and will look like finally.

ReST Online edtor

A very, very basic solution is the ReST Online Editor. It helps to make the very first steps with the rst format and is available on http://rst.ninjs.org/ But it does not reflect the TYPO3 specific rendering in no way.

Sphinx project

The perfect solution for rendering rst is the Sphinx project. Sphinx is the software, which is able to convert rst to various formats, like HTML, ePub and Latex. Latex is an intermediate format to render printable pdfs finally.

Detailed information about Sphinx and its history can be found at https://www.sphinx-doc.org/.

Sphinx within TYPO3

Thanks to Xavier Perseguers it is possible to use the Sphinx software within the TYPO3 backend. He created the extension “sphinx”. Through the extension manager, it is possible to download and install the software to the “typo3temp” directory.

It provides a rendering engine for all available rst documentation on your TYPO3 installation. Furthermore it is possible to edit the rst documentation online and view the result instantly.

Some time ago I wrote an article about setting up and using this extension http://typo3worx.eu/2016/01/sphinx-render-rest-documentation/.

Sandbox on GitHub

For testing purposes it is possible to get an individual sandbox on docs.typo3.org. Any commit to a sandbox will be rendered a couple of minutes later to docs.typo3.org, where you can check the success (or failure).

If you are interested in such a sandbox, contact Martin Bless. He will create a repository on GitHub an will invite to contribute to it. Once you have access to, you can try out any rst syntax and check how it will be rendered on the official documentation server of TYPO3.

Sphinx standalone

If you need the “full power” of Sphinx, a standalone installation is the way to go. There you can use own or modified Sphinx templates, in order to have a individual rendering. But the individual changes to the template will not be available on docs.typo3.org of course.

Getting Support

A documentation specific channel is available on slack. If you have any questions, about the rendering of TYPO3 documentation, just raise your hand there. Many people are around, who will try to help you.

If you do not have access to TYPO3 slack channels, head over to https://forger.typo3.org/slack. Just add your basic data, and you can use the knowledge of many nice people.

Conclusion

Contributing to TYPO3 Documentation is not that hard as most of you believed. It is hard, if the duty relies on shoulders of only some people. It will be “easy”, if many people contribute small pieces and make the official documentation a reliable and up to date source of information. … So get your hands dirty :-)