How to Start Documentation for Your TYPO3 Extension¶
This chapter 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 is the preferred workflow, but if you have problems with Docker see the alternative for rendering described under How to Render Documentation.
If necessary, ask for help as explained in Help & Support.
There are basically 2 ways to start, depending on whether you used the extension_builder to start your extension:
- Method 1: Start Documentation With 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 3 of the next section.
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 your extension, e.g.
cp -r TYPO3CMS-Example-ExtensionManual/Documentation <extension-directory>/
Add additional files
Some files are not mandatory, but it is recommended to use them:
- .gitignore is useful, so you don't accidentally commit
the generated documentation in
Documentation-GENERATED-tempto your Git repository.
- .editorconfig is useful, so you will use the recommended Coding Guidelines in your editor or IDE. You may need to set this up first (see EditorConfig Plugin 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
- .gitignore is useful, so you don't accidentally commit the generated documentation in
Edit the documentation
Start editing away. Use the existing text to guide you. Look at other extension manuals (for example sphinx) 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 Settings.cfg
Be sure to fill out
Settings.cfgcorrectly as described in Settings.cfg.
Render the Documentation Locally
Before you publish your changes, make sure the documentation is rendered correctly.
Look at Rendering Documentation With Docker for a quick start.
When You Are Done, Publish Your Changes
If you are working on your own extension, make it publicly available. The documentation will then automatically be rendered on docs.typo3.org.
Think about hosting your extension repository on GitHub. That way others can report issues and assist you by creating change requests for the documentation and code!