If you plan to upload your extension to the TYPO3 Extension Repository (TER), you should first consider adding documentation to your extension. Documentation will help users and administrators to install, configure and use your extension.
We will give you a short overview here, but for more information, please see the guide Writing documentation and specifically:
- General information about TYPO3 documentation: Basic Principles
- Get started using reST: reStructuredText & Sphinx
- More information about starting documentation for your TYPO3 extension: How to Document an Extension
- If you want to test your documentation, you need to render it: How to Render Documentation
The documentation platform https://docs.typo3.org centralizes documentation for every project. It supports different kinds of documentation:
- (recommended) A Sphinx project, stored within
- Other formats, such as a simple README file stored as
EXT:extkey/README.rst, see Start File
Sphinx is the format used for official TYPO3 documentation. A Sphinx-based documentation is a set of plain text files making up the chapters or sections of the documentation. It uses a markup language called “reStructuredText” (reST).
Advantages of this documentation format are numerous:
- Output formats: Sphinx projects may be automatically rendered as HTML or TYPO3-branded PDF.
- Cross-references: It is easy to cross-reference other chapters and sections of other manuals (either TYPO3 references or extension manuals). The links are automatically updated if pages or sections are moved.
- Collaboration: As the documentation is plain text, it is easy to work as a team on the same manual or quickly review changes using any versioning system.
Although it is possible to write every single line of a Sphinx-based documentation from scratch, the TYPO3 community provides tools that help to create a Sphinx documentation project:
Other formats besides the recommended format are possible as described in Start File.
However, please consider using the recommended format (sphinx project in
as described here.
There are some rendering issues with Markdown, so even if it is possible to use Markdown, please consider using reST, because that is what is commonly used in TYPO3 documentation projects and that is what is supported best.
A “README.rst” is a simple text file stored at the root of your extension directory and briefly describing the purpose of your extension. It is best suited when installing or using your extension is straightforward. The format of this file is reStructuredText, as for chapters of a Sphinx project.