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.

Tip

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:

  1. Method 1: Start Documentation With Extension Builder (extension_builder)
  2. 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 Documentation.tmpl directory in your extension folder. Rename this directory to Documentation.

mv Documentation.tmpl Documentation

Then continue with step 2 of the next section.

Warning

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

  1. 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 Documentation directory, so that the Documentation directory is a direct subdirectory of the extension, e.g.

    cp -r TYPO3CMS-Example-ExtensionManual/Documentation <extension-directory>/
    
  2. 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-temp to 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
    

    You may also want to consider adding CONTRIBUTING.rst and README.rst to your extension, if you plan to host your extension on a public repository.

  3. Edit documentation

    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.)

  4. Fill out composer.json

    Be sure to fill out composer.json correctly as described in composer.json.

  5. Fill out Settings.cfg

    Be sure to fill out Settings.cfg correctly as described in Settings.cfg.

  6. Render documentation

    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.

  7. 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.

Tip

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!