Start Extension Documentation From Example Manual

ちなみに

This page is a "quick start". If you are just getting started, you may want to look at How to Document an Extension and some of the resources listed there first.

This description uses the example extension 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.

ちなみに

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!