Note
This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.
If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.
Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.
How to document an extension
This chapter explains how to write documentation for a new extension.
This guide uses the example extension manual as a template for starting out. It contains a working navigation panel, a range of example content and adheres to the guidelines laid out in the Documentation content style guide chapter.
Rendering the documentation locally
Docker is required to run the rendering toolchain locally. By rendering the documentation this way, proofreading and checking for typos and testing links can be carried out before the documentation is committed. The Render documentation with the TYPO3 theme has more information on how this toolchain is set up and configured.
Using the documentation-draft branch to preview changes
Alternatively, a documentation-
branch can be created in the documentation repository.
Once committed, this will render the documentation and make it available publicly, but it will only be visible
when the "draft" drop-down is selected when viewing the rendered documentation. Documentation under the draft branch will not be indexed
by search engines. Visit the Supported branches section for more information.
Creating extension documentation using the sample manual
-
Clone the 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
Copied!Copy the entire
Documentation
directory, so that it is a subdirectory located within your extension, for example:cp -r TYPO3CMS-Example-ExtensionManual/Documentation <my-extension-directory>/
Copied! -
Add or modify additional files
- Make sure composer.json is up to date. (required)
- Make sure Settings: Documentation/guides.xml is up to date. (required)
- A .gitignore is useful, in order to
prevent accidentally committing the generated documentation in
Documentation-
to the Git repository. (recommended)GENERATED- temp - An .editorconfig is useful, so the recommended Coding Guidelines will be used within an editor or IDE.
# cp .gitignore (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.gitignore <my-extension-directory>/.gitignore # cp .editorconfig (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.editorconfig <my-extension-directory>/.editorconfig
Copied!If you plan to host your extension on a public repository, consider adding a CONTRIBUTING.rst and README.rst to help guide any future contributors.
-
Start adding documentation
Now it's time to start adding content. Reviewing existing guides can help you structure your own documentation. The news extension is a strong example of how extension documentation should be written and structured.
-
Populate composer.json
Complete the
composer.
as described in composer.json.json -
Populate guides.xml
Complete the
guides.
as described in Settings: Documentation/guides.xml.xml -
Render documentation
Before publishing changes, make sure the documentation is rendered correctly, either by rendering it locally or by using the draft branch to preview the changes.
-
Publish when ready
The documentation needs to be made publicly available.
In order to trigger the documentation rendering process, a webhook needs to be added.
Tip
Consider hosting your extension repository on either GitHub, Bitbucket or GitLab. That way others can report issues and assist you by creating change requests to help improve both the extensions documentation and the code.
Version numbers
docs.typo3.org does no longer show three level version numbers in form of Major.Minor.Patch
.
Only the first two levels are shown Major.Minor
.
This reduces the amount of documentation while keeping relevant information, as patch levels should not introduce breaking changes or new features.
Supported branches
The rendering supports two branches within repositories:
main
/master
-
Should contain the current development state, used for upcoming release. Every push to these branches triggers a new rendering, available at
https://
.docs. typo3. org/ p/<vendor>/<package>/ main/ en- us/ Both branch names are supported, but result in the same URL. Please use
main
,master
is only supported for backward compatibility. documentation-draft
-
Should contain a draft of the documentation. Every push to this branch triggers a new rendering, available at
https://
(same URL as main, except main is replaced by draft).docs. typo3. org/ p/<vendor>/<package>/ draft/ en- us/ This is not indexed by search engines. This branch can be used to test rendering before releasing a new version of an extension.
In order to test a different rendering, remove the branch, and create it again.