From bc2bbfa4df3c4144c3db398a30cd1a9fb50ec3db Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Tue, 17 Dec 2024 10:41:38 +0100 Subject: [PATCH] [FEATURE] Document new init command (#477) * [FEATURE] Document new init command * [FEATURE] Document new init command * [FEATURE] Document new init command --- .../Howto/WritingDocForExtension/Index.rst | 109 +++++------------- Documentation/Reference/GuidesXml.rst | 22 +++- .../Reference/RenderingContainer.rst | 12 +- Documentation/_Includes/_InitCommand.rst.txt | 4 + .../_Includes/_LocalRendering.rst.txt | 1 + 5 files changed, 64 insertions(+), 84 deletions(-) create mode 100644 Documentation/_Includes/_InitCommand.rst.txt diff --git a/Documentation/Howto/WritingDocForExtension/Index.rst b/Documentation/Howto/WritingDocForExtension/Index.rst index 91e96fc..8d4511b 100644 --- a/Documentation/Howto/WritingDocForExtension/Index.rst +++ b/Documentation/Howto/WritingDocForExtension/Index.rst @@ -3,7 +3,6 @@ .. include:: /Includes.rst.txt .. index:: Documentation; Extension .. _writing-doc-for-ext-start: -.. _how-to-start-docs-extension: .. _extension-documentation-files: .. _write-doc-extensions-intro: @@ -16,97 +15,49 @@ This chapter explains how to write documentation for a new extension. This guide uses the `example extension manual `__ as a template for starting out. -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 -:ref:`render-documenation-with-docker` has more information on how this toolchain is set up and configured. - -Using the documentation-draft branch to preview changes -------------------------------------------------------- - -Alternatively, a `documentation-draft` 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 :ref:`supported-branches` section for more information. - -Creating extension documentation using the sample manual --------------------------------------------------------- - -.. rst-class:: bignums-xxl - -#. Clone the sample extension manual - - In a temporary directory, clone the GitHub project - `sample extension manual `__ - - .. code-block:: bash - - git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual.git +.. _write-doc-extensions-intro-rendering: - Copy the entire :file:`Documentation` directory, so that it - is a subdirectory located within your extension, for example: - - .. code-block:: bash - - cp -r TYPO3CMS-Example-ExtensionManual/Documentation / - -#. Add or modify additional files - - * Make sure :ref:`t3coreapi:composer-json` is up to date. (*required*) - * Make sure :ref:`settings-cfg` is up to date. (*required*) - * A .gitignore is useful, in order to - prevent accidentally committing the generated documentation in - :file:`Documentation-GENERATED-temp` to the Git repository. (*recommended*) - * An .editorconfig is useful, so the - recommended :ref:`Coding Guidelines ` will be used within - an editor or IDE. - - .. code-block:: bash - - # cp .gitignore (make sure you don't accidentally overwrite existing one though!) - cp -n TYPO3CMS-Example-ExtensionManual/.gitignore /.gitignore - # cp .editorconfig (make sure you don't accidentally overwrite existing one though!) - cp -n TYPO3CMS-Example-ExtensionManual/.editorconfig /.editorconfig - - If you plan to host your extension on a public repository, consider - adding a CONTRIBUTING.rst - and :ref:`README.rst ` to help guide any future - contributors. - - -#. Start adding documentation +Rendering the documentation locally +=================================== - 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. +Use the following Docker command to render your documentation guide locally: -#. Populate composer.json +.. include:: /_Includes/_LocalRendering.rst.txt - Complete the :file:`composer.json` as described in :ref:`t3coreapi:composer-json`. +The :ref:`render-documenation-with-docker` has more information. -#. Populate guides.xml +.. _how-to-start-docs-extension: - Complete the :file:`guides.xml` as described in :ref:`settings-guides-xml`. +Use the init command to create the Documentation folder +======================================================= -#. Render documentation +The following Docker command helps you to create some basic documentation +including the required configuration file :file:`Documentation/guides.xml`: - Before publishing changes, make sure the documentation is rendered correctly, either - by :ref:`rendering it locally ` or by using the :ref:`draft branch ` - to preview the changes. +.. include:: /_Includes/_InitCommand.rst.txt -#. Publish when ready +The command creates a folder :path:`Documentation` in the directory it is called +from. This should be the root directory of your extension containing the +`composer.json `_. - The documentation needs to be :ref:`made publicly available `. +Follow the interactive dialoge. We suggest to use the option ReStructuredText (rst) +as this format provides the full power of the TYPO3 documentation theme. Using +Markdown (md) is an option for simple and quick one page documentation. - In order to trigger the documentation rendering process, a :ref:`webhook needs to be added `. +If your extension offers a main `Site set `_ +enter its name and path when prompted. This will regenerate ready to use +documentation about configuration for you. If you have more then one set you +can document the other sets manually. If you have no set, you need to write +the chapter your self. -.. tip:: +Make changes and try :ref:`rendering ` the new documentation. - 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. +To publish your documentation to https://docs.typo3.org +a :ref:`webhook needs to be added ` on GitHub, Bitbucket or GitLab. +A member of the Documentation Team has to approve your new documentation guide +for publishing. In case the Team has questions, please follow the thread +generated for your extension in the `TYPO3 slack organization `_ +in channel `#typo3-documentation `_. Version numbers =============== diff --git a/Documentation/Reference/GuidesXml.rst b/Documentation/Reference/GuidesXml.rst index 4e50470..838a3a9 100644 --- a/Documentation/Reference/GuidesXml.rst +++ b/Documentation/Reference/GuidesXml.rst @@ -9,19 +9,33 @@ Configuration of the rendering - guides.xml This XML file contains meta information and configuration used during rendering of a manual. -.. rubric:: Example: - .. literalinclude:: _guides-simple.xml :caption: Documentation/guides.xml +.. contents:: Table of Contents: + :local: + +.. _guides-xml-init: + +Init new guides.xml +=================== + +If you start a new documentation guide, for example in a TYPO3 extension, use the +`init` command: + +.. include:: /_Includes/_InitCommand.rst.txt + +And follow the interactive question. + .. hint:: If you are migrating from the legacy Sphinx-based rendering and still have a :file:`Documentation/Settings.cfg` you can use an automatic migration tool to :ref:`migrate the Settings.cfg into a guides.xml ` -.. contents:: Table of Contents: - :local: +.. _guides-xml-api: +guides.xml API +============== .. confval-menu:: :display: tree diff --git a/Documentation/Reference/RenderingContainer.rst b/Documentation/Reference/RenderingContainer.rst index be476ba..228dd94 100644 --- a/Documentation/Reference/RenderingContainer.rst +++ b/Documentation/Reference/RenderingContainer.rst @@ -11,4 +11,14 @@ contains the :path:`Documentation` folder: .. include:: /_Includes/_LocalRendering.rst.txt -.. todo: Document rendering container options here +.. _init-command: + +The init command +================ + +Use the `init` command to start writing TYPO3 documentation. + +.. include:: /_Includes/_InitCommand.rst.txt + +This command creates a `guides.xml `_ +configuration file and some example pages in folder :path:`Documentation`. diff --git a/Documentation/_Includes/_InitCommand.rst.txt b/Documentation/_Includes/_InitCommand.rst.txt new file mode 100644 index 0000000..cd2926c --- /dev/null +++ b/Documentation/_Includes/_InitCommand.rst.txt @@ -0,0 +1,4 @@ +.. code-block:: bash + :caption: Execute in extension root, the directory that contains your extensions composer.json + + docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest init diff --git a/Documentation/_Includes/_LocalRendering.rst.txt b/Documentation/_Includes/_LocalRendering.rst.txt index 7e6496c..a2e09b9 100644 --- a/Documentation/_Includes/_LocalRendering.rst.txt +++ b/Documentation/_Includes/_LocalRendering.rst.txt @@ -1,4 +1,5 @@ .. code-block:: bash + :caption: Execute in extension root, the directory that contains your extensions composer.json docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation