How to Start Documentation for Your TYPO3 Extension¶
This page describes how to create documentation for your extension using local editing and rendering with Docker. It requires Docker for running the rendering toolchain locally on your computer to check if the documentation is rendered correctly.
This page is a “quick start”. If you are just getting started, you may want to look at the resources on How to Document an Extension.
The documentation for extensions is structured in a similar way as the documentation for official manuals. See Directories and File Names for more details on these files.
There are basically 2 ways to start:
- Method 1: Start Documentation With Extension Builder (extension_builder)
- Method 2: Start Documentation From Example Manual
Method 1: Start Documentation With Extension Builder¶
If you used the extension_builder
to generate your extension, it will already have created a
directory in your extension folder. Rename this directory to
mv Documentation.tmpl Documentation
Then continue with step 2 of the next section.
Current and previous versions of the extension_builder generate documentation with tabs (instead of spaces). You should use spaces as specified in Coding Guidelines for reST Files. You should reformat the generated documentation before you proceed. Mixing tabs and spaces may cause inconsistent indenting and may lead to problems with the rendering.
Method 2: Start Documentation From Example Manual¶
Clone sample extension manual
In a temporary directory, clone the GitHub project sample extension manual
git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual.git
Move or copy the entire
Documentationdirectory, so that the Documentation directory is a direct subdirectory of the extension, e.g.
cp -r TYPO3CMS-Example-ExtensionManual/Documentation <extension-directory>/
Add or modify additional files
- (required) Make sure composer.json is up to date.
- (required) Make sure Settings.cfg is up to date.
- (recommended) .gitignore is useful, in order to
prevent accidentally commiting the generated documentation in
Documentation-GENERATED-tempto the Git repository.
- (recommended) .editorconfig is useful, so the recommended Coding Guidelines will be used within editor or IDE. EditorConfig Plugin contains further information for PhpStorm.
# cp .gitignore (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.gitignore <extension-directory>/.gitignore # cp .editorconfig (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.editorconfig <extension-directory>/.editorconfig
Start editing away. Use the existing text to guide you. Look at other extension manuals (for example form) for inspiration. (Click on “Related Links” to jump to the repository or scroll to bottom of rendered page and click on “View page source” to see reST source.)
Fill out composer.json
Be sure to fill out
composer.jsoncorrectly as described in composer.json.
Fill out Settings.cfg
Be sure to fill out
Settings.cfgcorrectly as described in Settings.cfg.
Before publishing changes, make sure the documentation is rendered correctly.
Look at Rendering Documentation with Docker for a quick start, how to render locally.
There is also a draft branch that allows to render a preview at docs.typo3.org.
Publish when done
If you are working on your own extension, make it publicly available.
In order to trigger documentation rendering on the documentation server you have to add a webhook, see Webhook.
Think about hosting your extension repository on GitHub, Bitbucket or GitLab. That way others can report issues and assist you by creating change requests for the documentation and code!