From e926b174eca45ba76735a577e35519e89444966d Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 12 Dec 2023 22:26:07 +0100 Subject: [PATCH 01/45] [FEATURE] Introduce PHP-based rendering --- Documentation/guides.xml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/guides.xml diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 00000000..e22b9e2b --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + From bc30031d6b07a7e6e24b34796e87ad65c62008b7 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sat, 13 Jan 2024 18:56:52 +0100 Subject: [PATCH 02/45] [TASK] Adjust migration page (#348) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Adjust rendering page Releases: draft * Update Documentation/WritingDocForExtension/Migrate.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../WritingDocForExtension/Migrate.rst | 247 +++--------------- 1 file changed, 41 insertions(+), 206 deletions(-) diff --git a/Documentation/WritingDocForExtension/Migrate.rst b/Documentation/WritingDocForExtension/Migrate.rst index 19dde7b7..2f0e7f33 100644 --- a/Documentation/WritingDocForExtension/Migrate.rst +++ b/Documentation/WritingDocForExtension/Migrate.rst @@ -5,225 +5,60 @@ .. _migrate: .. _register-for-rendering: -=========================== -Register for docs.typo3.org -=========================== +============================================= +Migration: From Sphinx to PHP-based rendering +============================================= -Follow the :ref:`register-necessary-steps` in order to have extension -documentation rendered on docs.typo3.org out of the box. -When migrating existing documentation, :ref:`migrate-info-about-changes` might be interesting as well. +.. note:: -.. contents:: Table of Contents - :local: + Since the beginning of 2024 you can switch to the new, PHP-based reStructured + Text rendering to try it out. The new rendering will become mandatory in + August 2024. -.. _migrate-necessary-steps: -.. _register-necessary-steps: +The main difference that concerns you is that the new PHP-base rendering +requires a file called :file:`Documentation/guides.xml` for configuration +while in Sphinx rendering a file called :file:`Docuemtation/Settings.cfg` was +used. In the transition period we detect if a file called +:file:`Documentation/guides.xml` is present and then switch to the new +PHP-based rendering. -Necessary steps -=============== +Create the settings file :file:`Documentation/guides.xml` +========================================================= -Walk through the following steps in defined order. Proceed with next step only -if the previous step was successful. +The Docker container for the new PHP-based rendering additionally contains +a migration tool. This tool can be used to automatically create a +:file:`Documentation/guides.xml` from the information contained in your +:file:`Documentation/Settings.cfg`. -.. rst-class:: bignums-xxl +`Docker `__ needs to be installed on your +operating system for the tool to work: -#. Add mandatory :file:`composer.json`, see :ref:`t3coreapi:composer-json` +.. code-block:: shell - This file is necessary, in order to determine required information, like - vendor, package name and supported TYPO3 version. + docker run --rm --pull always \ + -v $(pwd):/project \ + -it ghcr.io/typo3-documentation/render-guides:latest \ + migrate Documentation -#. Add :file:`Documentation/Settings.cfg`, see :ref:`settings-cfg` +Try out the rendering locally +============================= - If this file does not exist, documentation will get rendered, but title will - not be displayed in the left sidebar. +Use our Docker container to render your documentation locally. Read more about +:ref:`local rendering `. - This requirement may be dropped in the future.For now it is necessary to at - least add a minimal :file:`Documentation/Settings.cfg`. +Improve your documentation to render without warning +==================================================== - Example for very minimal Settings.cfg, for full example see - :ref:`settings-cfg`: +Have a look at :ref:`Common pitfalls ` that might cause +rendering warnings. - .. code-block:: cfg +If you believe you found a bug in the new PHP-based rendering, please open +an `Issue on GitHub `__. - [general] +Recommended: Activate automatic testing +======================================= - project = Extension name +It is recommended to use an automatic workflow on GitHub Or Gitlab to +ensure the extension's documentation renders without warnings. -#. Add new webhook, see :ref:`webhook` - - The legacy webhook is no longer necessary, as explained in - :ref:`webhook-legacy`. Instead the new webhook has to be added as described - at :ref:`webhook`. - - In case the old hook is in play, remove it first, and add the new one - instead. - -#. Trigger webhook for released versions, - see :ref:`reregister-versions` (optional) - - In case documentation for already released versions should be rendered again, - follow :ref:`reregister-versions`. - - It will explain how the process of rendering - can be triggered once more for already released versions. - -#. Request redirects (optional) - - This step adds work load to a small team. - Please check whether there is a need to request redirects. - - Inform the TYPO3 Documentation Team, within `#typo3-documentation - `_ Slack channel. Registration - for Slack is available at `my.typo3.org - `__. - Alternatively, a redirect can be requested by commenting in `this GitHub - issue `__. - - The team will setup the redirects from existing legacy rendering to current - rendering: - - * legacy URL: :samp:`https://docs.typo3.org/typo3cms/extensions///` - * new URL: :samp:`https://docs.typo3.org/p////` - -All future versions will now be rendered, see :ref:`workflow-extension-release`. -Also some branches will be rendered, see :ref:`supported-branches`. - - -.. index:: - Documentation; Webhooks - Git; Commits -.. _migrate-extension-release: -.. _workflow-extension-release: - -Workflow of an extension release -================================ - -For full information about publishing extensions check :ref:`t3coreapi:publish-extension`. - -The following steps only describe what's necessary for documentation publishing and for -the link to the documentation to be displayed on extensions.typo3.org: - -#. Add :ref:`webhook` (if not already done). - -#. Tag the Git commit with a valid version: :ref:`supported-version-numbers`. - -#. Push (publish) the Git tag. - -Publishing a tag will trigger rendering of documentation for that tag. -The result will be published on docs.typo3.org. -Furthermore a JSON file which provides info about the new available documentation -will be automatically generated on the documentation server. - -This file is used by extensions.typo3.org to find matching documentation. -extensions.typo3.org will only show the link to the latest available version. -This has to match the released version on docs.typo3.org. -No fallback is in place (for example `main` will not be linked by default). - -Please note that it might take some time until extensions.typo3.org displays changed URLs to docs.typo3.org. -The information needs to be picked up by a command. -Caches for detail page need to be invalidated, and SOLR index needs to be updated. - -.. index:: Rendering; Version numbers -.. _migrate-version-numbers: -.. _supported-version-numbers: - -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. - -.. index:: Rendering; Branches -.. _migrate-branches: -.. _supported-branches: - -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 - :samp:`https://docs.typo3.org/p///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 - :samp:`https://docs.typo3.org/p///draft/en-us/` - (same URL as main, except *main* is replaced by *draft*). - - - 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. - -.. _migrate-url-structure: -.. _url-structure: - -URL structure -============= - -The URL structure now consists of the following parts: - -:samp:`https://docs.typo3.org/////` - -Example: https://docs.typo3.org/p/helhum/typo3-console/main/en-us/ - -``type`` - One of: - - ``p`` - Provides documentation for composer packages (TYPO3 third party extensions) - - ``c`` - Provides documentation for TYPO3 core extensions. - - ``m`` - Provides official manuals (guides, tutorials, references). - - ``h`` - Provides the homepage of docs.typo3.org - - ``other`` - Provides further documentation, for example for `Surf - `_ or `Fluid - `_ - -``vendor`` - Collects all packages of the same vendor, for example "typo3" or a company - providing extensions. Same as on packagist.org. - -``package`` - Defines the package. Same as on packagist.org. - -``version`` - Defines the version, either in form of "Major.Minor" or ``main`` or - ``draft``. - -``locale`` - Defines the locale, for example ``en-us`` or ``fr-fr``. - -.. _migrate-info-about-changes: -.. _migrate-existing-documentation: - -Info about changes -================== - -Since May 29th 2019 a new infrastructure is in place at docs.typo3.org. -This requires some migration tasks, in order to ensure that extension documentation -is rendered on docs.typo3.org. - -Existing legacy documentation is kept until end of 2020. -Each documentation contains an information block that it's outdated, -together with a link to the necessary steps. - -In order to migrate, follow :ref:`migrate-necessary-steps`. +.. todo: Add a link to the according chapter From 951121e1b06e760c5dcd71938457d08e70a03a2c Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sat, 13 Jan 2024 19:22:43 +0100 Subject: [PATCH 03/45] [TASK] Adjust rendering page (#347) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Adjust rendering page Releases: draft * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Apply suggestions from code review * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Apply suggestions from code review --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/RenderingDocs/Index.rst | 135 +++++++------ .../RenderingDocs/Troubleshooting.rst | 189 ------------------ 2 files changed, 77 insertions(+), 247 deletions(-) delete mode 100644 Documentation/RenderingDocs/Troubleshooting.rst diff --git a/Documentation/RenderingDocs/Index.rst b/Documentation/RenderingDocs/Index.rst index 3e45d649..45e72a26 100644 --- a/Documentation/RenderingDocs/Index.rst +++ b/Documentation/RenderingDocs/Index.rst @@ -10,97 +10,116 @@ .. _render-documenation-with-docker: .. _render-documentation-with-docker: +========================================= +Render documentation with the TYPO3 theme +========================================= -=========================== -How to render documentation -=========================== +.. contents:: -This page explains how to render a manual locally on your machine -with Docker in order to test the rendering. +Rendering the :file:`Documentation` folder locally with Docker +============================================================== -Run these commands in a terminal in the parent directory of the directory -:file:`Documentation`. You should use a bash compatible shell, if possible. +You can render the documentation of an official TYPO3 manual or a third-party +manual with the following steps: -If you run into a problem while rendering, check :ref:`rendering-docs-troubleshooting`, -`report an issue `__ -or :ref:`ask for help `. +#. Clone the repository containing the documentation. +#. Navigate to the extension's root folder, the directory which contains the + :file:`composer.json`. -.. rst-class:: bignums-xxl +#. Check if there is documentation to be rendered: - #. Install Docker: https://docs.docker.com/install/ + A folder called :file:`Documentation` containing at least the files + :file:`Index.rst` and :file:`guides.xml`. - #. Preparations +#. Choose your prefered method of rendering (See below): - The docker image is not listed on Docker Hub (hub.docker.com) anymore, therefore some preparations - need to be done once: +Make sure that `Docker `__ is installed on your system. - .. code-block:: bash +.. tabs:: - # pull 'latest' version from GitHub container repository - docker pull ghcr.io/t3docs/render-documentation + .. group-tab:: Linux - # The "real" tag is independent of the container repository, - # so let's just create that extra "real" and "generic" tag - docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation + .. code-block:: bash - # verify it worked - docker run --rm t3docs/render-documentation --version + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + xdg-open "Documentation-GENERATED-temp/Index.html" - #. Make 'dockrun_t3rd' available in current terminal + .. group-tab:: MacOS - .. code-block:: bash + .. code-block:: bash - eval "$(docker run --rm t3docs/render-documentation show-shell-commands)" + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + open "Documentation-GENERATED-temp/Index.html" - This will run the Docker container and print out shell code. Once "eval-uated" - the code defines a helper function named `dockrun_t3rd`. This function relieves - you of the work of setting the volumes and rights correctly when running the - container and ensures a folder for the rendering results is provided. Executing - the code with `eval` defines the function for your current terminal. Don't forget - the quotes around everything that goes into eval. Either define the function each - time you open a new terminal window or add the line to the startup file of your - shell like `~/.bashrc` or `.zshrc`. + .. group-tab:: Windows - #. Run dockrun_t3rd + .. code-block:: powershell - .. code-block:: bash + New-Item -ItemType Directory -Force -Path ".\Documentation-GENERATED-temp" + docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + start "Documentation-GENERATED-temp/Index.html" - dockrun_t3rd makehtml +Publishing extension documentation to docs.typo3.org +==================================================== - This will automatically find the documentation in the - :file:`Documentation` subfolder. It will create a directory - :file:`Documentation-GENERATED-temp` and write the results there. +For your documentation to be published to https://docs.typo3.org, your +TYPO3 extension has to have a valid :file:`composer.json` and either a folder +called :file:`Documentation` with a :file:`Documentation/Index.rst` and +a :file:`Documentation/guides.xml` or a :file:`README.rst` / :file:`README.md` +in the extensions root directory. - #. Open generated documentation +The extension has to be publicly available on GitHub or GitLab. You have to +establish a :ref:`Webhook ` and the Documentation Team has to +:ref:`approve ` your first rendering. - Look at the output of the previous command to see where the - generated documentation is located or use one of these commands - to directly open the start page in a browser: +Introduce automatic testing for extension documentation +======================================================= - .. tabs:: +It is recommended to make sure your documentation always renders without +warning. On GitHub or GitLab you can introduce actions that test your +documentation automatically: - .. group-tab:: Linux +.. tabs:: - .. code-block:: bash + .. group-tab:: GitHub - xdg-open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + .. code-block:: yaml + :caption: .github/workflows/documentation.yml - .. group-tab:: MacOS + name: test documentation - .. code-block:: bash + on: [ push, pull_request ] - open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + jobs: + tests: + name: documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 - .. group-tab:: Windows + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log - .. code-block:: powershell + .. group-tab:: GitLab - start "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + .. code-block:: bash + :caption: .gitlab-ci.yml + stages: + - test -.. toctree:: - :hidden: - :glob: + test_documentation: + stage: test + script: + - mkdir -p Documentation-GENERATED-temp + - docker run --rm --pull always -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log + tags: + - docker - Troubleshooting diff --git a/Documentation/RenderingDocs/Troubleshooting.rst b/Documentation/RenderingDocs/Troubleshooting.rst deleted file mode 100644 index 2ec540c1..00000000 --- a/Documentation/RenderingDocs/Troubleshooting.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: bash -.. index:: Rendering; Troubleshooting -.. _rendering-docs-troubleshooting: - -=========================================== -Troubleshooting local rendering with Docker -=========================================== - -If you run into problems, here are some -helpful hints on how to solve them. - -Remember, you can always ask questions in the **#typo3-documentation** -channel on Slack! `Register for slack `__ -and join the channel, if you have not done so already. - - -.. index:: Rendering; Problems with `source < (docker run ...` -.. _render-troubleshooting-source: - -Problems with `source < (docker run ...` -======================================== - - -.. code-block:: bash - - source <(docker run --rm t3docs/render-documentation show-shell-commands) - dockrun_t3rd makehtml - -If these commands do not work on your platform, try this instead: - -.. code-block:: bash - - mkdir -p ~/bin - docker run --rm t3docs/render-documentation show-shell-commands > ~/bin/t3docs - source ~/bin/t3docs - - -.. _docker-troubleshoot-sample-output-ok: - -Sample output without errors -============================ - -When you run render, you should see some output. If -everything works correctly, the final output should look like this: - -.. code-block:: none - - ... - - We saw these exitcodes (code, count): - { - "0": 86 - } - exiting with exitcode 0 - - ... - -Relevant is the exitcode 0. It indicates that everything executed -smoothly. - - -.. index:: Rendering; Errors -.. _render-troubleshooting-errors: - -Errors that break the rendering -=============================== - -If there are errors which break the rendering, you may see something like: - -.. code-block:: none - - We saw these exitcodes (code, count): - { - "0": 53, - "3": 1, - "22": 7 - } - exiting with exitcode 0 - -Do not let the message *"exiting with exitcode 0"* mislead you. You've -definitely got a problem that needs to be taken care of. - -.. important:: - - If the rendering is not executed correctly, the files in - :file:`Documentation-GENERATED-temp` will still contain - the last rendered results (which are now no longer up to - date) ! - -Scroll back in your terminal to see where the errors occurred: - -.. code-block:: none - - ================================================== - 18-Make-and-build/run_Check-requirements.py - exitcode: 22 - - ================================================== - 20-Postprocess/run_00-Check-requirements.py - exitcode: 22 - - ================================================== - 22-Assemble-results/run_01-Assemble-html-pdf-and-more.py - exitcode: 22 - - ================================================== - 26-Collect-buildinfo/run_Check-requirements.py - exitcode: 22 - -Everything with exitcode != 0 is relevant. Here, we see a problem -with the requirements. This is usually caused by an incorrect path -for including a file. - -Remember, every file includes :file:`Includes.rst.txt` at the top. Check your -latest changes. - -.. code-block:: none - - .. include:: /Includes.rst.txt - -Correct the path, so it will point to the existing Includes.rst.txt (which -should be located in the directory :file:`Documentation`. - - -.. index:: Rendering; Warnings -.. _render-troubleshooting-warnings: - -Warnings -======== - -There may be problems which will not break the rendering but which -should be taken care of. Warnings are listed in the file -:file:`Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt` - - -.. index:: Rendering; Incremental -.. _render-troubleshooting-incremental: - -Incremental Rendering -===================== - -After you make changes, you can initiate rendering again. - -This will cause .rst files, that has been changed, to be rendered again. - -If the menu (toctree) has been changed, the menu may not be correctly -displayed for unchanged files because they will not be rendered again. - -If you need a complete rendering, delete the :file:`Documentation-GENERATED-temp` -folder and render again, for example: - -.. code-block:: bash - - rm -rf Documentation-GENERATED-temp - - -Get detailed information -======================== - -If you create a directory :file:`tmp-GENERATED-temp` before you start the rendering, -the toolchain will not remove this directory when it is done. Usually -it cleans up after itself and this directory will be created and then removed. - -The directory contains some additional information for the individual scripts -that have been run. In case of cryptic error messages which you have trouble -interpreting, you may check these files for more information. - -Look for files with ending :file:`err.txt` that are not empty. - -Example output: - -:file:`tmp-GENERATED-temp/RenderDocumentation/2019-05-19_06-37-50_072139/18-Make-and-build/40-Html/xeq-40-Make-html-1-err.txt` - -.. code-block:: bash - - Traceback (most recent call last): - File "/usr/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 303, in main - args.warningiserror, args.tags, args.verbosity, args.jobs) - File "/usr/local/lib/python2.7/site-packages/sphinx/application.py", line 191, in __init__ - self.setup_extension(extension) - File "/usr/local/lib/python2.7/site-packages/sphinx/application.py", line 411, in setup_extension - self.registry.load_extension(self, extname) - File "/usr/local/lib/python2.7/site-packages/sphinx/registry.py", line 318, in load_extension - raise ExtensionError(__('Could not import extension %s') % extname, err) - ExtensionError: Could not import extension sphinxcontrib.googlechart (exception: cannot import name Directive) - - Extension error: - Could not import extension sphinxcontrib.googlechart (exception: cannot import name Directive) From 3d492d905010df063a1bdaf063029bbe921b3063 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sun, 14 Jan 2024 09:15:15 +0100 Subject: [PATCH 04/45] [TASK] Introduce automatic testing (#349) * [TASK] Replace .. code-block:: rest with .. code-block:: rst Releases: draft * [TASK] Remove the custom configuration schemes We do not support them anymore in the new rendering Releases: draft * [TASK] Remove outdated information about subtree split This has been outdated since TYPO3 9, the links dont work anymore Release: draft * [TASK] Fix outdated references Release: draft * [TASK] Remove Glossary section We don't support it anymore and it was never really used. Release: draft * [TASK] Introduce automatic testing So that the documentation renders without Release: draft * [TASK] Restore information from migration section That was still linked from these files --- .github/workflows/documentation.yml | 17 ++ Documentation/BasicPrinciples.rst | 8 +- .../GeneralConventions/CodingGuidelines.rst | 10 +- Documentation/GeneralConventions/Glossary.rst | 37 ---- .../GuidelinesForImages.rst | 2 +- .../GeneralConventions/HowToUpdateDocs.rst | 2 +- Documentation/GeneralConventions/Index.rst | 2 +- .../GeneralConventions/ReviewInformation.rst | 8 +- Documentation/WritingDocForExtension/FAQ.rst | 5 +- .../WritingDocForExtension/Index.rst | 40 +++++ .../WritingDocForExtension/Webhook.rst | 2 +- .../WritingDocsOfficial/GithubMethod.rst | 2 +- Documentation/WritingReST/BasicRestSyntax.rst | 2 +- Documentation/WritingReST/CheatSheet.rst | 48 +++--- .../WritingReST/CommonPitfalls/Headers.rst | 4 +- .../WritingReST/CommonPitfalls/Hyperlinks.rst | 8 +- .../WritingReST/CommonPitfalls/Indents.rst | 4 +- .../CommonPitfalls/InlineStyle.rst | 4 +- .../WritingReST/CommonPitfalls/Lists.rst | 6 +- .../WritingReST/Reference/Code/Confval.rst | 161 ------------------ .../WritingReST/Reference/Code/Phpdomain.rst | 2 +- .../Reference/Content/Admonitions.rst | 10 +- .../Reference/Content/BoldItalic.rst | 4 +- .../WritingReST/Reference/Content/Links.rst | 30 ++-- .../Reference/Content/SpecialCharacters.rst | 2 +- .../WritingReST/Reference/Content/Tables.rst | 8 +- .../Reference/Content/Versions.rst | 12 +- .../Reference/Content/YoutubeVideos.rst | 2 +- .../Reference/Graphics/Diagrams.rst | 26 +-- .../WritingReST/Reference/Graphics/Graphs.rst | 10 +- .../WritingReST/Reference/Graphics/Images.rst | 8 +- .../Reference/Lists/BulletLists.rst | 6 +- .../Reference/Menus/HeadlinesAndSection.rst | 8 +- .../Reference/Menus/MenuHierarchy.rst | 6 +- .../WritingReST/Reference/Menus/Orphans.rst | 2 +- 35 files changed, 180 insertions(+), 328 deletions(-) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..79ac662e --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,17 @@ +name: test documentation + +on: [ push, pull_request ] + +jobs: + tests: + name: documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log diff --git a/Documentation/BasicPrinciples.rst b/Documentation/BasicPrinciples.rst index 02477f93..4f542899 100644 --- a/Documentation/BasicPrinciples.rst +++ b/Documentation/BasicPrinciples.rst @@ -312,13 +312,7 @@ Examples for system extensions are: * `ext:rte_ckeditor `__ Note, that if your system has been installed with Composer, not all system extensions may exist -in the system, if each system extension has been required separately as "subtree splitted packages" -(not as `typo3/cms`). Since TYPO3 9, installation of "subtree splitted packages" is mandatory. - -For more information on subtree split, see - -* `Usetypo3: The TYPO3 Subtree Split and Composer `__ -* :ref:`Installation and Upgrade guide: Composer migration ` +in the system. .. index:: pair: System extensions; Documentation diff --git a/Documentation/GeneralConventions/CodingGuidelines.rst b/Documentation/GeneralConventions/CodingGuidelines.rst index 735e9ec9..c986538c 100644 --- a/Documentation/GeneralConventions/CodingGuidelines.rst +++ b/Documentation/GeneralConventions/CodingGuidelines.rst @@ -48,7 +48,7 @@ Whitespace and indentation Example: -.. code-block:: rest +.. code-block:: rst :linenos: .. image:: /Images/a4.jpg @@ -236,7 +236,7 @@ discouraged either. The changelog has a title anchor, so you can easily link to it with `:ref:`. -.. code-block:: rest +.. code-block:: rst :ref:`ext_core:feature-101544-1691063522` @@ -269,14 +269,14 @@ element or clicked one after the other, use *>* as separator and use Examples: -.. code-block:: rest +.. code-block:: rst Select :guilabel:`File > Open` How it looks: Select :guilabel:`File > Open` -.. code-block:: rest +.. code-block:: rst Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend. @@ -296,7 +296,7 @@ When pointing out keyboard shortcuts or keystroke sequences, use Example: -.. code-block:: rest +.. code-block:: rst Press :kbd:`ctrl` + :kbd:`s` diff --git a/Documentation/GeneralConventions/Glossary.rst b/Documentation/GeneralConventions/Glossary.rst index d5693849..db9178de 100644 --- a/Documentation/GeneralConventions/Glossary.rst +++ b/Documentation/GeneralConventions/Glossary.rst @@ -202,40 +202,3 @@ third party extension ViewHelper Our community agreed on this spelling. - - - -Glossary -======== - -.. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary -.. Creating a glossary with terms that you can refer to - obtaining a link. - -What terms mean: - -.. glossary:: - - third party extension - Any extension that is not part of the :term:`TYPO3 Core`. - - TYPO3 CMS - The TYPO3 content management system. - - TYPO3 Core - ... - - TYPO3 Core Team - This is the team that drives the development of the :term:`TYPO3 Core`. - - -.. See `Issue on GitHub - `__ - for discussion about spelling. - -.. See open issue about `Clarifying terms - `__ - -.. Open related issue `Several changes for making TYPO3 concepts easier - to understand for new users - `__ - diff --git a/Documentation/GeneralConventions/GuidelinesForImages.rst b/Documentation/GeneralConventions/GuidelinesForImages.rst index 906eab7e..5b0de5a1 100644 --- a/Documentation/GeneralConventions/GuidelinesForImages.rst +++ b/Documentation/GeneralConventions/GuidelinesForImages.rst @@ -79,7 +79,7 @@ Here are some :ref:`examples for screenshots //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 + :samp:`https://docs.typo3.org/p///draft/en-us/` + (same URL as main, except *main* is replaced by *draft*). + + + 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. + + .. toctree:: :maxdepth: 1 :hidden: diff --git a/Documentation/WritingDocForExtension/Webhook.rst b/Documentation/WritingDocForExtension/Webhook.rst index de771b40..20a5e572 100644 --- a/Documentation/WritingDocForExtension/Webhook.rst +++ b/Documentation/WritingDocForExtension/Webhook.rst @@ -31,7 +31,7 @@ each new extension when requesting rendering for the first time. In order to approve an extension, the following things need to apply: #. The extension needs to be published in TER under the same extension key as - claimed by :ref:`t3coreapi:composer.json `. + claimed by :ref:`composer.json `. #. The Git Repository is referenced from TER detail view page. diff --git a/Documentation/WritingDocsOfficial/GithubMethod.rst b/Documentation/WritingDocsOfficial/GithubMethod.rst index 6c91e20c..37c78de2 100644 --- a/Documentation/WritingDocsOfficial/GithubMethod.rst +++ b/Documentation/WritingDocsOfficial/GithubMethod.rst @@ -54,7 +54,7 @@ Workflow #1: "Edit on GitHub" Every page you edit is written in reST format, when it comes to making minor amendments no prior knowledge of editing .rst files is required. However, when you are - ready to make more advanced changes, you can :ref:`learn more about working with reST here.` + ready to make more advanced changes, you can :ref:`learn more about working with reST here. ` 7. Preview your changes: diff --git a/Documentation/WritingReST/BasicRestSyntax.rst b/Documentation/WritingReST/BasicRestSyntax.rst index e3e690a6..df0d683f 100644 --- a/Documentation/WritingReST/BasicRestSyntax.rst +++ b/Documentation/WritingReST/BasicRestSyntax.rst @@ -57,7 +57,7 @@ The following directive inserts an image in the rendered page. All lines beginni two must be indented to the same leve. The convention is to use 4 spaces for one level of indentation. -.. code-block:: rest +.. code-block:: rst .. image:: someimage.png :class: with-border with-shadow diff --git a/Documentation/WritingReST/CheatSheet.rst b/Documentation/WritingReST/CheatSheet.rst index bc873ad1..ca5d3dc2 100644 --- a/Documentation/WritingReST/CheatSheet.rst +++ b/Documentation/WritingReST/CheatSheet.rst @@ -24,7 +24,7 @@ Cheat sheet: reST & Sphinx Every reST (.rst) file should use these underlining styles. In reST, you can use different styles in any order you want. These are our conventions for TYPO3 documentation. -.. code-block:: rest +.. code-block:: rst :linenos: ======== @@ -50,7 +50,7 @@ styles in any order you want. These are our conventions for TYPO3 documentation. * line 1-3: This is the doc title. Every .rst file should have one. * line 7: header label. This can be used for cross-referencing to this section: - .. code-block:: rest + .. code-block:: rst :ref:`header1` @@ -76,7 +76,7 @@ External links method 1: -.. code-block:: rest +.. code-block:: rst `anchor text `__ @@ -86,7 +86,7 @@ method 1: method 2: "External Hyperlink Targets": -.. code-block:: rest +.. code-block:: rst Check out more information on t3o_ @@ -107,13 +107,13 @@ When linking within docs.typo3.org, you should use this method of cross-referenc Use it to link to a section in this manual: -.. code-block:: rest +.. code-block:: rst :ref:`intersphinx` A section with the label **intersphinx** must exist! It is placed before the header: -.. code-block:: rest +.. code-block:: rst .. _intersphinx: @@ -122,7 +122,7 @@ A section with the label **intersphinx** must exist! It is placed before the hea Or, when cross-referencing to other manuals: -.. code-block:: rest +.. code-block:: rst :ref:`shortcut:label` @@ -171,13 +171,13 @@ Preventing links Prevent unintentional linking of simple URLs with the :code:`:samp:` directive: -.. code-block:: rest +.. code-block:: rst The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. and emphasize parts of the URL with curly braces: -.. code-block:: rest +.. code-block:: rst The *route* is the "speaking URL" as a whole without the domain part, for example :samp:`https://example.org/{}`. @@ -234,7 +234,7 @@ More text. Source: -.. code-block:: rest +.. code-block:: rst To create a bullet list: @@ -268,7 +268,7 @@ More text. Source: -.. code-block:: rest +.. code-block:: rst To create a numbered list: @@ -306,7 +306,7 @@ Code block directive Source: -.. code-block:: rest +.. code-block:: rst :linenos: .. code-block:: php @@ -355,7 +355,7 @@ For inline code or for other semantic markup of special texts, use text roles. Source: -.. code-block:: rest +.. code-block:: rst :linenos: :php:`$result = $a + 23;` @@ -380,7 +380,7 @@ Normal text, **bold text** and *italic text*. Source: -.. code-block:: rest +.. code-block:: rst Normal text, **bold text** and *italic text*. @@ -399,14 +399,14 @@ Source: Source: -.. code-block:: rest +.. code-block:: rst .. image:: /Images/a4.jpg :class: with-shadow Another example: -.. code-block:: rest +.. code-block:: rst .. image:: /Images/a4.jpg :class: with-shadow @@ -432,7 +432,7 @@ Another example: Source: -.. code-block:: rest +.. code-block:: rst .. youtube:: wNxO-aXY5Yw @@ -468,7 +468,7 @@ This is an example with a code block (:rst:`::`) embedded in the sections. Source: -.. code-block:: rest +.. code-block:: rst .. rst-class:: bignums @@ -476,7 +476,7 @@ Source: Source: - .. code-block:: rest + .. code-block:: rst .. image: some_image.png :class: with-shadow @@ -497,7 +497,7 @@ With Big Numbers XXL Source: - .. code-block:: rest + .. code-block:: rst /Images/a4.jpg :class: with-shadow @@ -508,7 +508,7 @@ With Big Numbers XXL Source: -.. code-block:: rest +.. code-block:: rst .. rst-class:: bignums-xxl @@ -516,7 +516,7 @@ Source: Source: - .. code-block:: rest + .. code-block:: rst .. image: some_image.png :class: with-shadow @@ -745,7 +745,7 @@ Source: Source: -.. code-block:: rest +.. code-block:: rst .. graphviz:: @@ -794,7 +794,7 @@ Source: Source: -.. code-block:: rest +.. code-block:: rst .. uml:: diff --git a/Documentation/WritingReST/CommonPitfalls/Headers.rst b/Documentation/WritingReST/CommonPitfalls/Headers.rst index 05a6806b..7367c433 100644 --- a/Documentation/WritingReST/CommonPitfalls/Headers.rst +++ b/Documentation/WritingReST/CommonPitfalls/Headers.rst @@ -21,7 +21,7 @@ throughout the docs is to to keep it the same length. Correct syntax ============== -.. code-block:: rest +.. code-block:: rst ================ This Is a Header @@ -39,7 +39,7 @@ Wrong syntax ============ -.. code-block:: rest +.. code-block:: rst Another Header ------------ diff --git a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst b/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst index a814c678..41975a53 100644 --- a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst +++ b/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst @@ -14,14 +14,14 @@ at the bottom on this page. Correct syntax ============== -.. code-block:: rest +.. code-block:: rst `anchor text `__ Example: -.. code-block:: rest +.. code-block:: rst `T3O `__ @@ -40,7 +40,7 @@ opening `<`. Wrong syntax ------------ -.. code-block:: rest +.. code-block:: rst Wrong: `T3O`__ @@ -56,7 +56,7 @@ Missing `_` or `__` at the end: Wrong Syntax ------------ -.. code-block:: rest +.. code-block:: rst Wrong: `T3O ` diff --git a/Documentation/WritingReST/CommonPitfalls/Indents.rst b/Documentation/WritingReST/CommonPitfalls/Indents.rst index 7c851057..721b0027 100644 --- a/Documentation/WritingReST/CommonPitfalls/Indents.rst +++ b/Documentation/WritingReST/CommonPitfalls/Indents.rst @@ -16,7 +16,7 @@ Always indent correctly (4 spaces per level) Correct syntax -------------- -.. code-block:: rest +.. code-block:: rst .. image:: /Images/a4.jpg :width: 100px @@ -35,7 +35,7 @@ Incorrect syntax Here, `:width:` is indented with only 2 spaces. The image will not be rendered at all! -.. code-block:: rest +.. code-block:: rst .. image:: /Images/a4.jpg :width: 100px diff --git a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst b/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst index 01974d2e..9721b90c 100644 --- a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst +++ b/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst @@ -15,7 +15,7 @@ the markup and the styled text. Correct syntax -------------- -.. code-block:: rest +.. code-block:: rst This is normal text. **This is bold text.** @@ -28,7 +28,7 @@ This is normal text. **This is bold text.** Wrong syntax ------------ -.. code-block:: rest +.. code-block:: rst This is normal text. ** This is bold text.** diff --git a/Documentation/WritingReST/CommonPitfalls/Lists.rst b/Documentation/WritingReST/CommonPitfalls/Lists.rst index 7ef806f1..7668328c 100644 --- a/Documentation/WritingReST/CommonPitfalls/Lists.rst +++ b/Documentation/WritingReST/CommonPitfalls/Lists.rst @@ -20,7 +20,7 @@ Correct syntax Example 1: Bullet list ~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: rest +.. code-block:: rst this is some text @@ -42,7 +42,7 @@ more text Example 2: List with sublist ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: rest +.. code-block:: rst this is some text @@ -69,7 +69,7 @@ this is more text Wrong syntax ------------ -.. code-block:: rest +.. code-block:: rst this is some text * this is a list item diff --git a/Documentation/WritingReST/Reference/Code/Confval.rst b/Documentation/WritingReST/Reference/Code/Confval.rst index 74897ac8..3796237a 100644 --- a/Documentation/WritingReST/Reference/Code/Confval.rst +++ b/Documentation/WritingReST/Reference/Code/Confval.rst @@ -29,79 +29,6 @@ Each configuration value name may only be used once. In large references with different contexts you can define individual configuration schemas for each context. -Define a configuration schema -============================= - -The directive :rst:`confval` is predefined and can not be configured. - -To introduce a new configuration schema add the following section to -the manuals :file:`Documentation/Settings.cfg`: - -.. code-block:: none - :caption: EXT:my_extension/Documentation/Settings.cfg - - - [sphinx_object_types_to_add] - - my-custom-directive = my-custom-directive // my-custom-directive // My Cool Configuration Value section - -It is possible to define several configuration schemes by listing them each in -one line, for example in the TypoScript reference we have one configuration -scheme for each content object like :typoscript:`TEXT`, :typoscript:`COA` -or :typoscript:`FILE`: - -.. code-block:: none - :caption: reference-typoscript/Documentation/Settings.cfg - - - [sphinx_object_types_to_add] - - cobj-coa = cobj-coa // cobj-coa // Content object COA - cobj-file = cobj-file // cobj-file // Content object FILE - cobj-text = cobj-text // cobj-text // Content object TEXT - -The can then be used to define configuration values for each TypoScript -content object type using the directive used in the first part of the definition -after the `=` sign, for example: - -.. cobj-text:: value - - :Data type: string / stdWrap - - Text, which you want to output. - -.. code-block:: rst - - .. cobj-text:: value - - :Data type: string / string / stdWrap - - Text, which you want to output. - -You can link to the specific configuration value by second part of the -definition, the one after the first `//` sign: - -**Example** - -Use the :cobj-text:`value` property of the :typoscript:`TEXT` content element. -Wrap it by :cobj-text:`stdWrap`. Note that the :cobj-text:`stdWrap` property -works different from the one from the :cobj-coa:`stdWrap` property of the -:typoscript:`COA` content object... - -.. code-block:: rst - - Use the :cobj-text:`value` property of the :typoscript:`TEXT` content element. - Wrap it by :cobj-text:`stdWrap`. Note that the :cobj-text:`stdWrap` property - works different from the one from the :cobj-coa:`stdWrap` property of the - :typoscript:`COA` content object... - -The third entry of the configuration is used as label in the automatic Index -entries (:ref:`genindex.rst `): - -.. figure:: /Images/CustomConfigurationIndexEntries.png - - Automatic entries on the page :ref:`genindex.rst `. - Examples ======== @@ -148,91 +75,3 @@ Configuration value with default value :Path: $GLOBALS > TYPO3_CONF_VARS > SYS File mode mask for Unix file systems (when files are uploaded/created). - -Custom configuration schemas ----------------------------- - -:typoscript:`TEXT` - -.. cobj-text:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`TEXT` content element - - -:typoscript:`COA` - -.. cobj-coa:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`COA` content element - -.. cobj-coa:: 1,2,3, ... - - :Data type: conten object - - Any content object to be displayed - - -:typoscript:`FILE` - -A file can also be put in the property :cobj-coa:`1,2,3, ...` of a -:typoscript:`COA` content object. - -.. cobj-file:: file - - :Data type: file - - The file to be displayed - -.. cobj-file:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`FILE` content element - - -.. code-block:: rst - - :typoscript:`TEXT` - - .. cobj-text:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`TEXT` content element - - - :typoscript:`COA` - - .. cobj-coa:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`COA` content element - - .. cobj-coa:: 1,2,3, ... - - :Data type: conten object - - Any content object to be displayed - - - :typoscript:`FILE` - - A file can also be put in the property :cobj-coa:`1,2,3, ...` of a - :typoscript:`COA` content object. - - .. cobj-file:: file - - :Data type: file - - The file to be displayed - - .. cobj-file:: stdWrap - - :Data type: stdWrap - - stdWrap properties in the :typoscript:`FILE` content element diff --git a/Documentation/WritingReST/Reference/Code/Phpdomain.rst b/Documentation/WritingReST/Reference/Code/Phpdomain.rst index 55673ffa..dec9275e 100644 --- a/Documentation/WritingReST/Reference/Code/Phpdomain.rst +++ b/Documentation/WritingReST/Reference/Code/Phpdomain.rst @@ -182,7 +182,7 @@ Interfaces :param string $errorFile: Name of the file the error occurred in :param int $errorLine: Line number where the error occurred :returntype: bool - :throws: :php:class:`TYPO3\\CMS\\Core\\Error\\Exception` + :throws: :php:`TYPO3\CMS\Core\Error\Exception` .. php:const:: ERROR_HANDLED diff --git a/Documentation/WritingReST/Reference/Content/Admonitions.rst b/Documentation/WritingReST/Reference/Content/Admonitions.rst index 2d116cf3..5489bc40 100644 --- a/Documentation/WritingReST/Reference/Content/Admonitions.rst +++ b/Documentation/WritingReST/Reference/Content/Admonitions.rst @@ -19,7 +19,7 @@ Examples See also -------- -.. code-block:: rest +.. code-block:: rst .. seealso:: `Admonitions `__ @@ -33,7 +33,7 @@ See also Note ---- -.. code-block:: rest +.. code-block:: rst .. note:: A note @@ -47,7 +47,7 @@ Note Tip --- -.. code-block:: rest +.. code-block:: rst .. tip:: A tip @@ -63,7 +63,7 @@ and **tip** is more commonly used in the documentation. Warning ------- -.. code-block:: rest +.. code-block:: rst .. warning:: Some text pointing out something that people should be warned about. @@ -80,7 +80,7 @@ severity of the warning must be stressed. Attention --------- -.. code-block:: rest +.. code-block:: rst .. attention:: A attention diff --git a/Documentation/WritingReST/Reference/Content/BoldItalic.rst b/Documentation/WritingReST/Reference/Content/BoldItalic.rst index 9b90e889..23a608ba 100644 --- a/Documentation/WritingReST/Reference/Content/BoldItalic.rst +++ b/Documentation/WritingReST/Reference/Content/BoldItalic.rst @@ -13,7 +13,7 @@ Bold, Italic etc. Bold ==== -.. code-block:: rest +.. code-block:: rst This is normal text. **This is bold text** @@ -27,7 +27,7 @@ This is normal text. **This is bold text** Italic ====== -.. code-block:: rest +.. code-block:: rst This is normal text. *This is italic text.* diff --git a/Documentation/WritingReST/Reference/Content/Links.rst b/Documentation/WritingReST/Reference/Content/Links.rst index 56500736..8415a9ab 100644 --- a/Documentation/WritingReST/Reference/Content/Links.rst +++ b/Documentation/WritingReST/Reference/Content/Links.rst @@ -19,7 +19,7 @@ In Sphinx you can use several types of links: :ref:`external-links` for linking to other sources outside of the reST docs on docs.typo3.org. - .. code-block:: rest + .. code-block:: rst `anchor text `__ @@ -28,7 +28,7 @@ In Sphinx you can use several types of links: :ref:`Cross-Referencing ` (`:ref:`) for linking to other sections of the same manual on docs.typo3.org with Intersphinx mechanism - .. code-block:: rest + .. code-block:: rst :ref:`anchor text ` @@ -39,7 +39,7 @@ In Sphinx you can use several types of links: If your link target is in another manual (for example "Getting Started Tutorial", you must add the shortcut (here: `t3start`) for the other manual: - .. code-block:: rest + .. code-block:: rst :ref:`anchor text ` @@ -62,7 +62,7 @@ How to create links is described in more detail in the next sections. being automatically generated from simple URLs – mostly used in connection with hypothetical domains. - .. code-block:: rest + .. code-block:: rst :samp:`` @@ -71,7 +71,7 @@ How to create links is described in more detail in the next sections. are domains for use in URLs where the domain does not matter, but serves as a placeholder. The TYPO3 documentation uses a defined set of them. - .. code-block:: rest + .. code-block:: rst :samp:`https://example.org/news/` @@ -111,7 +111,7 @@ External link as anonymous URL Syntax ~~~~~~ -.. code-block:: rest +.. code-block:: rst `Anchor text `__ @@ -120,7 +120,7 @@ Syntax Example ~~~~~~~ -.. code-block:: rest +.. code-block:: rst `Sphinx hyperlinks `__ @@ -143,7 +143,7 @@ Syntax Same as :ref:`anonymous URL `, but with one underscore instead of 2. -.. code-block:: rest +.. code-block:: rst `Anchor text `_ @@ -178,7 +178,7 @@ Here, the link target *columns-inline* will be defined. * Place the link target definition directly before the section header: -.. code-block:: rest +.. code-block:: rst .. _columns-inline: @@ -255,7 +255,7 @@ Again, we want to link to the labels `columns-inline` and `This-is-ABC`. But since the labels are now in a different manuals, we need to prefix the names of that manuals: -.. code-block:: rest +.. code-block:: rst :ref:`t3tca:columns-inline` :ref:`t3upgrade:This-is-ABC` @@ -292,7 +292,7 @@ Example 2: Specify anchor text If we want to control the anchor text ourselves, we can do so by writing: -.. code-block:: rest +.. code-block:: rst :ref:`this is our linktext ` @@ -336,7 +336,7 @@ to wrap the URL. For example: -.. code-block:: rest +.. code-block:: rst The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. @@ -346,7 +346,7 @@ The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. To emphasize parts of the URL, use curly braces: -.. code-block:: rest +.. code-block:: rst The *route* is the "speaking URL" as a whole without the domain part, for example :samp:`https://example.org//{}`. @@ -390,13 +390,13 @@ above such as :samp:`https://staging.example.org` and For example: -.. code-block:: rest +.. code-block:: rst The class :php:`MailMessage` can be used to generate and send a mail without using Fluid: - .. code-block:: rest + .. code-block:: rst $mail = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class); $mail diff --git a/Documentation/WritingReST/Reference/Content/SpecialCharacters.rst b/Documentation/WritingReST/Reference/Content/SpecialCharacters.rst index c2e26ad2..027680f7 100644 --- a/Documentation/WritingReST/Reference/Content/SpecialCharacters.rst +++ b/Documentation/WritingReST/Reference/Content/SpecialCharacters.rst @@ -113,7 +113,7 @@ Using U+2420 symbol for space Code ---- -.. code-block:: rest +.. code-block:: rst * ``:literal:`␠abc``` → :literal:`␠abc` * ```␠abc``` → `␠abc` diff --git a/Documentation/WritingReST/Reference/Content/Tables.rst b/Documentation/WritingReST/Reference/Content/Tables.rst index 2227d3cd..776f3f5f 100644 --- a/Documentation/WritingReST/Reference/Content/Tables.rst +++ b/Documentation/WritingReST/Reference/Content/Tables.rst @@ -17,7 +17,7 @@ responsive. Grid table ========== -.. code-block:: rest +.. code-block:: rst +----------+----------+ | Header 1 | Header 2 | @@ -48,7 +48,7 @@ Simple table ============ -.. code-block:: rest +.. code-block:: rst ======== ======== Header 1 Header 2 @@ -73,7 +73,7 @@ http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables CSV table ========= -.. code-block:: rest +.. code-block:: rst .. csv-table:: Numbers :header: "Header 1", "Header 2" @@ -105,7 +105,7 @@ template. If you want your .rst file to be correctly rendered on other platforms as well (for example GitHub), you should not use this. -.. code-block:: rest +.. code-block:: rst .. t3-field-list-table:: :header-rows: 1 diff --git a/Documentation/WritingReST/Reference/Content/Versions.rst b/Documentation/WritingReST/Reference/Content/Versions.rst index e42f2811..5fa2d875 100644 --- a/Documentation/WritingReST/Reference/Content/Versions.rst +++ b/Documentation/WritingReST/Reference/Content/Versions.rst @@ -20,7 +20,7 @@ and semi-automatically be removed after one or two versions. Versionadded ============ -.. code-block:: rest +.. code-block:: rst .. versionadded:: 10.2 Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based @@ -34,7 +34,7 @@ For emphasis, the directive can also be placed into one of the :ref:`admonitions `: -.. code-block:: rest +.. code-block:: rst .. tip:: .. versionadded:: 10.2 @@ -49,20 +49,20 @@ For emphasis, the directive can also be placed into one of the Deprecated ========== -.. code-block:: rest +.. code-block:: rst .. deprecated:: 10.2 The hook shown here is deprecated since TYPO3 10.2 - use a custom - :ref:`PSR-15 middleware` instead. + PSR-15 middleware instead. .. deprecated:: 10.2 The hook shown here is deprecated since TYPO3 10.2 - use a custom - :ref:`PSR-15 middleware` instead. + PSR-15 middleware instead. Versionchanged ============== -.. code-block:: rest +.. code-block:: rst .. versionchanged:: 10.4.34 The bug ... was fixed with version 10.4.23 ... diff --git a/Documentation/WritingReST/Reference/Content/YoutubeVideos.rst b/Documentation/WritingReST/Reference/Content/YoutubeVideos.rst index 1c5de558..938ee79e 100644 --- a/Documentation/WritingReST/Reference/Content/YoutubeVideos.rst +++ b/Documentation/WritingReST/Reference/Content/YoutubeVideos.rst @@ -24,7 +24,7 @@ Embed YouTube videos 2. Embed the Video using the ID - .. code-block:: rest + .. code-block:: rst 2018-01-19 by Mathias Schreiber diff --git a/Documentation/WritingReST/Reference/Graphics/Diagrams.rst b/Documentation/WritingReST/Reference/Graphics/Diagrams.rst index 52e11dc4..d016de1b 100644 --- a/Documentation/WritingReST/Reference/Graphics/Diagrams.rst +++ b/Documentation/WritingReST/Reference/Graphics/Diagrams.rst @@ -71,7 +71,7 @@ Activity diagram --> "Page.onDestroy()" -->(*) -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -158,7 +158,7 @@ Class diagram String password } -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -225,7 +225,7 @@ Component diagram [Example 1] --> [Folder 3] [Folder 3] --> [Frame 4] -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -283,7 +283,7 @@ Deployment diagram } } -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -366,7 +366,7 @@ rendering process of the TYPO3 documentation. php2 <--> mysql php2 <--> elastic -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -425,7 +425,7 @@ The latest icons can be integrated directly via remote url. DEV_TYPO3(typo3,"TYPO3",participant,orange) -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -453,7 +453,7 @@ Maths P(y|\mathbf{x}) \mbox{ or } f(\mathbf{x})+\epsilon end note -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -485,7 +485,7 @@ Misc You can use [[http://plantuml.com/start links in notes]] also. end note -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -528,7 +528,7 @@ Object diagram Object05 o-- "4" Object06 Object07 .. Object08 : some labels -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -569,7 +569,7 @@ Sequence diagram Alice -> Bob: Another authentication Request Alice <-- Bob: another authentication Response -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -612,7 +612,7 @@ State diagram } } -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -662,7 +662,7 @@ Timing diagram +500 is ok @200 <-> @+150 : {150 ms} -.. code-block:: rest +.. code-block:: rst .. uml:: @@ -705,7 +705,7 @@ Use Case diagram (checkout) -- clerk } -.. code-block:: rest +.. code-block:: rst .. uml:: diff --git a/Documentation/WritingReST/Reference/Graphics/Graphs.rst b/Documentation/WritingReST/Reference/Graphics/Graphs.rst index f0e71900..03979724 100644 --- a/Documentation/WritingReST/Reference/Graphics/Graphs.rst +++ b/Documentation/WritingReST/Reference/Graphics/Graphs.rst @@ -63,7 +63,7 @@ Undirected graph user -- view -- controller -- model; } -.. code-block:: rest +.. code-block:: rst .. graphviz:: :caption: The MVC pattern divides the application into three global layers. @@ -157,7 +157,7 @@ Directed graph list -> blog_entity [label="② Retrieve all blog posts";constraint=false]; } -.. code-block:: rest +.. code-block:: rst .. graphviz:: :caption: In this request, a list of blog posts is displayed. @@ -270,7 +270,7 @@ Dot layout engine end [shape=Msquare]; } -.. code-block:: rest +.. code-block:: rst .. graphviz:: @@ -337,7 +337,7 @@ Neato layout engine fontsize=20; } -.. code-block:: rest +.. code-block:: rst .. graphviz:: @@ -422,7 +422,7 @@ Fdp layout engine clusterC -- clusterB; } -.. code-block:: rest +.. code-block:: rst .. graphviz:: diff --git a/Documentation/WritingReST/Reference/Graphics/Images.rst b/Documentation/WritingReST/Reference/Graphics/Images.rst index d1146667..a74abf55 100644 --- a/Documentation/WritingReST/Reference/Graphics/Images.rst +++ b/Documentation/WritingReST/Reference/Graphics/Images.rst @@ -64,7 +64,7 @@ Example 1: Scaled image with shadow and link target :class: with-shadow :scale: 50 -.. code-block:: rest +.. code-block:: rst :linenos: .. image:: /Images/a4.jpg @@ -102,7 +102,7 @@ Example 2: Image with caption This is the image caption -.. code-block:: rest +.. code-block:: rst :linenos: .. figure:: /Images/a4.jpg @@ -127,7 +127,7 @@ Example 3: Image with fixed width :width: 100px -.. code-block:: rest +.. code-block:: rst :linenos: .. image:: /Images/a4.jpg @@ -156,7 +156,7 @@ Some text ... (will be displayed on the right of the image). .. rst-class:: clear-both -.. code-block:: rest +.. code-block:: rst .. image:: /Images/a4.jpg :alt: Left floating image diff --git a/Documentation/WritingReST/Reference/Lists/BulletLists.rst b/Documentation/WritingReST/Reference/Lists/BulletLists.rst index 0dab0477..ad7b0e25 100644 --- a/Documentation/WritingReST/Reference/Lists/BulletLists.rst +++ b/Documentation/WritingReST/Reference/Lists/BulletLists.rst @@ -43,7 +43,7 @@ Numbered lists: Example 1: List with sublist items ================================== -.. code-block:: rest +.. code-block:: rst * item 1 * item 2 is a longer text with line breaks. We can format and @@ -78,7 +78,7 @@ Example 2: List with sublist and error This example will not work as expected, because the extra lines for the sublist are missing. -.. code-block:: rest +.. code-block:: rst * item 1 * item 2 @@ -106,7 +106,7 @@ Example 3: List with sublist and whitespace error If you only use one the sublist is interpreted like a citation. -.. code-block:: rest +.. code-block:: rst * item 1 * item 2 diff --git a/Documentation/WritingReST/Reference/Menus/HeadlinesAndSection.rst b/Documentation/WritingReST/Reference/Menus/HeadlinesAndSection.rst index 6129a15a..c6559184 100644 --- a/Documentation/WritingReST/Reference/Menus/HeadlinesAndSection.rst +++ b/Documentation/WritingReST/Reference/Menus/HeadlinesAndSection.rst @@ -47,7 +47,7 @@ is split into "sections" instead. Those sections are identified by titles which Example ======= -.. code-block:: rest +.. code-block:: rst ======== DocTitle @@ -84,7 +84,7 @@ may be longer, not shorter. Example 1: This Works ~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: rest +.. code-block:: rst ========= Example 1 @@ -93,7 +93,7 @@ Example 1: This Works Example 2: This Works Too ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: rest +.. code-block:: rst ============== Example 1 @@ -102,7 +102,7 @@ Example 2: This Works Too Example 3: This Does not Work ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: rest +.. code-block:: rst ======= Example 1 diff --git a/Documentation/WritingReST/Reference/Menus/MenuHierarchy.rst b/Documentation/WritingReST/Reference/Menus/MenuHierarchy.rst index 878a6543..a66762a6 100644 --- a/Documentation/WritingReST/Reference/Menus/MenuHierarchy.rst +++ b/Documentation/WritingReST/Reference/Menus/MenuHierarchy.rst @@ -30,7 +30,7 @@ General rules for using `..toctree::` 1. Each .rst file should have a doctitle, for example: - .. code-block:: rest + .. code-block:: rst ========== Some Title @@ -51,7 +51,7 @@ Example: hidden This will create a menu, using the header of Introduction/Index.rst and Configuration/Index.rst. The menu structure is not displayed as a table of contents on the current page ("hidden"). -.. code-block:: rest +.. code-block:: rst :linenos: .. toctree:: @@ -70,7 +70,7 @@ meaning you do not need to explicitly write the file names. If new files are add the menu will be updated automatically. Only the doctitle (first header in file) will be displayed (titlesonly). -.. code-block:: rest +.. code-block:: rst :linenos: .. toctree:: diff --git a/Documentation/WritingReST/Reference/Menus/Orphans.rst b/Documentation/WritingReST/Reference/Menus/Orphans.rst index 346b8673..aad78b73 100644 --- a/Documentation/WritingReST/Reference/Menus/Orphans.rst +++ b/Documentation/WritingReST/Reference/Menus/Orphans.rst @@ -18,6 +18,6 @@ menu somewhere. Sphinx will issue a warning if this isn’t the case. This will suppress the warning. -.. code-block:: rest +.. code-block:: rst :orphan: From 7a2710bcb7fe5a75f35fd5873bb1a5a400feb33d Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sun, 14 Jan 2024 09:58:14 +0100 Subject: [PATCH 05/45] [TASK] Remove orphaned Preface page (#354) --- Documentation/Preface/Index.rst | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 Documentation/Preface/Index.rst diff --git a/Documentation/Preface/Index.rst b/Documentation/Preface/Index.rst deleted file mode 100644 index f074af6d..00000000 --- a/Documentation/Preface/Index.rst +++ /dev/null @@ -1,8 +0,0 @@ -:orphan: - - -======= -Preface -======= - -This chapter was moved to :ref:`about`. \ No newline at end of file From 6884e465130b61949f45bf6f928d652694755ad0 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 15 Jan 2024 15:00:41 +0100 Subject: [PATCH 06/45] [TASK] Update information on how to handle Core changes (#360) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Update information on how to handle Core changes * Update Documentation/Maintainers/Changelog.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/Maintainers/Changelog.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> (cherry picked from commit 276c5a4348acaa1f258648dfbfead42339b2d35e) --- .../GeneralConventions/HowToUpdateDocs.rst | 178 ------------------ Documentation/Index.rst | 1 - Documentation/Maintainers/Changelog.rst | 131 +++++++++++++ 3 files changed, 131 insertions(+), 179 deletions(-) delete mode 100644 Documentation/GeneralConventions/HowToUpdateDocs.rst create mode 100644 Documentation/Maintainers/Changelog.rst diff --git a/Documentation/GeneralConventions/HowToUpdateDocs.rst b/Documentation/GeneralConventions/HowToUpdateDocs.rst deleted file mode 100644 index c8226054..00000000 --- a/Documentation/GeneralConventions/HowToUpdateDocs.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: - Documentation; Update - Documentation; New releases -.. _howto-update-docs: -.. _update-docs: - -===================================== -Update documentation for new releases -===================================== - -Once a new TYPO3 release comes out, the main documentation (for example :ref:`t3coreapi:start`, -:ref:`t3tca:start` etc.) must be updated. - -Here, we describe some best practices for updating the official documentation -for a new TYPO3 release. We stick to the core conventions as much as possible because that -makes it easier for everyone to contribute to documentation and core. - - -.. index:: - Documentation; Deprecations - Documentation; Breaking changes - -How to handle deprecations and breaking changes -=============================================== - -.. important:: - - We used to follow the conventions, that deprecated features were entirely removed from the - documentation as soon as they are deprecated. This no longer applies: We recommend to - add some information about the deprecation where this may be helpful. - -This has the disadvantage that the documentation must be modified twice: once to point out -the deprecation, and finally to remove it. - -But, on the other hand, we have found that it is more user friendly to **document the -deprecation and the alternative to make migration easier**. This mean, we do not (yet) -remove the deprecated information entirely. This gives people more -time to adjust to the changes. Also, deprecated features may still be used, but if the -documentation were removed entirely, a search for documentation would direct everyone to a previous -version where the feature is still documented without mentioning the deprecation. - -See the next section for some examples. - -.. index:: - Documentation; Version hints - reST; Version hints - reST directives; deprecated - reST directives; versionadded - reST directives; versionchanged - -How to add version hints -======================== - -Example, how you can point out **deprecations**:: - - .. deprecated:: 10.2 - The hook shown here is deprecated since TYPO3 10.2 - use a custom - :ref:`PSR-15 middleware` instead. - -New **feature**:: - - .. versionadded:: 10.2 - Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based - event dispatching system. - - -Changes:: - - .. versionchanged:: 2.3.1 - This feature was changed ... - -Further information: - -* General section about reST CGL: :ref:`version-hints` - -.. index:: - reST; Changelog links - reST roles; doc - -Link to changelog -================= - -How to link to the changelog is described in :ref:`link-to-changelog`. - -.. code-block:: rst - - :ref:`ext_core:feature-101544-1691063522` - -For this to work, ext_core must be defined in :file:`Settings.cfg` - - -.. index:: Updates; Issues - -Issues -====== - -* It is not necessary to create an issue for every change. - - -.. index:: pair: Updates; Commit messages - -Commit messages -=============== - -The commit message can point out the releases to which the change should apply -(as in the core commits), for example `Releases: main, 11.5`, see -:ref:`general-conventions-commit-messages`. - -You can link to the issue for the changes in the team repository, for example:: - - Related: TYPO3-Documentation/T3DocTeam#121 - - -.. index:: Updates; Several releases - -Applying changes to several releases -==================================== - -Sometimes a necessary change applies to several major versions. Example: A change in -the documentation is necessary in current main (12.0) and also in 11.5 branch. - -If this is the case, it is recommended to: - -* apply the change to the lower version (11.5 in our example) first, and then create - another PR for the higher version making necessary additional changes. This is the - reverse order of what is being used in the Core! -* The person merging the commit should take care of merging into other branches as well - (in case that is necessary). This is the same convention as in the core. -* The changes can be bundled into one commit and the commit / PR can have a subject - such as: - -.. code-block:: none - - [TASK] Update with changes from 11.5.3 - -This makes it easier to find related changes and check for which version a branch was last -updated. - - -.. index:: - Documentation; Status - reST roles; Status - -How to mark what state a manual is in -===================================== - -In order to keep track of which changes have already been applied and give readers hints -about how up to date a manual is, you can optionally add a "Status" to the start page -(:file:`Documentation/Index.rst`). - -For example:: - - :Status: - ok (Fully reviewed for TYPO3 9.5.9 on July 22, 2019) - -If the manual has not been fully reviewed, but all changelogs up to 9.5.9 have been -applied, you might use:: - - - :Status: - needs review (All changelogs <= TYPO3 9.5.9 have been applied) - -See :ref:`t3start:start`. - - -Work in progress -================ - -Several suggestions have been made to improve the process but these still require -more work or a decision, for example - -* `Link to changelog `__ -* `How can we get changes added to documentation early? And what is master: main or latest release? `__ -* `Add information when page / manual was last reviewed and what state it is in `__ -* `Find a workflow for reviewing / updating / refining manuals `__ - diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 59825269..c00a85a6 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -126,7 +126,6 @@ What's new in this guide? :caption: ADVANCED HowToAddTranslation/Index - GeneralConventions/HowToUpdateDocs GeneralConventions/ReviewInformation .. toctree:: diff --git a/Documentation/Maintainers/Changelog.rst b/Documentation/Maintainers/Changelog.rst new file mode 100644 index 00000000..23ca82fd --- /dev/null +++ b/Documentation/Maintainers/Changelog.rst @@ -0,0 +1,131 @@ +.. include:: /Includes.rst.txt +.. highlight:: rst +.. index:: + Documentation; Update + Documentation; New releases +.. _howto-update-docs: +.. _update-docs: + +=================================== +Apply changelog entries to the docs +=================================== + +Whenever a change to the TYPO3 Core potentially affects the users a changelog +entry is created or edited, for example: + +.. deprecated:: 12.3 + The hook shown here is deprecated since TYPO3 12.3, use the event XYZ + instead. + +Each Core change affecting the changelog automatically creates an +`Issue in the repository Changelog-To-Doc `. +New issues here should be treated with priority. + +.. index:: pair: Updates; Commit messages + +Commit messages +=============== + +All changes that are related to such an issue should contain a reference in +their commit message to the issue, for example + +.. code-block:: text + :caption: Example commit message + + [FEATURE] Add ApplicationContext to TypoScript data + + Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790 + Releases: main + +See also: :ref:`general-conventions-commit-messages`. + +.. index:: + Documentation; Deprecations + reST directives; deprecated +.. _changelog-deprecations: + +Deprecations in the changelog +============================= + +All information about deprecations should be marked with the :rst:`.. deprecated::` +directive and the version of deprecation. + +.. deprecated:: 12.3 + The hook shown here is deprecated since TYPO3 12.3, use the event XYZ + instead. + +.. code-block:: rst + + .. deprecated:: 12.3 + The hook shown here is deprecated since TYPO3 12.3, use the event XYZ + instead. + +In the ideal workflow a deprecation option will be removed with a breaking +change in the next major version. We can then just remove the deprecated section. + +Using the correct directive will help the documentation team to find and remove +deprecation hints in later versions. + +.. index:: + Documentation; Breaking changes + reST directives; versionchanged +.. _changelog-breaking-changes: + +Breaking changes in the changelog +================================= + +Ideally a breaking change was prepared by a :ref:`deprecation ` +in the previous version. In this case we can just remove the deprecated section. + +When important concepts changed that might confuse the users we sometimes leave +a :rst:`.. versionchanged::` directive to inform users where to head now. + +.. versionchanged:: 11.5 + The widely used :php:`->execute()` method has been split into: + php:`->executeQuery()` and :php:`->executeStatement()`. Read more. + +.. code-block:: rst + + .. versionchanged:: 11.5 + The widely used :php:`->execute()` method has been split into: + php:`->executeQuery()` and :php:`->executeStatement()`. Read more. + +For emphasis you can also put the version changed directive into a warning or +info box: + +.. warning:: + .. versionchanged:: 11.5 + The widely used :php:`->execute()` method has been split into: + php:`->executeQuery()` and :php:`->executeStatement()`. Read more. + +.. code-block:: rst + + .. warning:: + .. versionchanged:: 11.5 + The widely used :php:`->execute()` method has been split into: + php:`->executeQuery()` and :php:`->executeStatement()`. Read more. + +Using the correct directive will help us to track down and remove these hints +in later versions. + +.. index:: + reST directives; versionadded +.. _changelog-feature: + +New features in the changelog +============================= + +When adding a new feature to the docs that is not yet availible in all supported +TYPO3 versions, it can be helpful to mark it with the :rst:`.. versionadded::` +directive: + +.. versionadded:: 13.0 + A PHP attribute :php:`\TYPO3\CMS\Core\Attribute\AsEventListener` is + available to autoconfigure a class as an event listener... + +This directive not only highlights new features but also assists users who +are reading the manual in a version that does not align with their installation, +ensuring clarity in cases where feature compatibility may differ. + +The documentation team removes these directives when the feature is present in +all supported TYPO3 versions. From c815805f69b27d527f9828a69f565c0c2feb6b7f Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 15 Jan 2024 11:04:21 +0100 Subject: [PATCH 07/45] [TASK] Remove Tools to Edit Rest page (#357) The information is outdated, the suggested php storm plugins are not really helpful, the section on visual studio just general information how to create code snippets. (cherry picked from commit a0fb736aae45ebf23fd0b7398d3adc60dd386dc2) --- Documentation/Index.rst | 1 - Documentation/ToolsEditRest/Index.rst | 154 ------------------ .../WritingDocForExtension/Index.rst | 3 +- .../WritingDocsOfficial/LocalEditing.rst | 2 +- Documentation/WritingReST/Index.rst | 4 +- 5 files changed, 3 insertions(+), 161 deletions(-) delete mode 100644 Documentation/ToolsEditRest/Index.rst diff --git a/Documentation/Index.rst b/Documentation/Index.rst index c00a85a6..395129d2 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -117,7 +117,6 @@ What's new in this guide? WritingContent/Index WritingDocForExtension/Index WritingDocsOfficial/Index - ToolsEditRest/Index RenderingDocs/Index GitHub/Index diff --git a/Documentation/ToolsEditRest/Index.rst b/Documentation/ToolsEditRest/Index.rst deleted file mode 100644 index 5440cf31..00000000 --- a/Documentation/ToolsEditRest/Index.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Editors -.. _tools: -.. _tools-for-editing-rest: - -====================== -Tools for Editing reST -====================== - -We will cover some IDEs here, that may be useful if you edit locally -with the :ref:`docs-contribute-git-docker`. - -When editing reST files locally, you should use an editor or IDE with -good support for syntax highlighting and marking errors in reST. - -* `PhpStorm `__ is commonly used by - developers in the TYPO3 community. It does however cost money. PhpStorm - comes with a number of plugins for TYPO3, for example for TypoScript and Fluid. -* **Visual Studio Code** also comes with plugins for TYPO3 and for reStructuredText. - And it is free. - -Other alternatives can be found in the "Free Editors" section of -`StackOverflow: reStructuredText tool support `__. - -The editor or IDE should ideally have the following features: - -* syntax highlighting for reST -* show syntax errors -* provide possibility to use (configurable) code snippets for easy insertion of - directives -* provide keyboard shortcuts and configurable commands for running - Docker -* built in spell checking (English) - -Setup your editor / IDE to use the .editorconfig file, which already -exists in most documentation repositories. This will set up your -editor / IDE to comply with our :ref:`basic coding guidelines -`. - -You may have to install -an additional plugin, see `EditorConfig `__. - - -.. index:: reST; Visual Studio Code - -Visual Studio Code -================== - -restructuredText Plugin ------------------------ - -#. Open Extensions (:kbd:`CTRL+SHIFT+X`) -#. Enter *reStructuredText* in search box -#. Select LeXtudio extension -#. Press install - -.. image:: /Images/vscode-rest-ext.png - :class: with-shadow - -The LeXtudio extension comes with some built in code snippets. - -You can: - -* show all snippets by pressing :kbd:`CTRL+Space` -* start entering the beginning of a snippet name and press tab - -.. tip:: - - Try this now by typing image and then TAB. - -.. image:: /Images/VsStudio/vscodesnippets.gif - :class: with-shadow - -You can easily extend the snippets by adding **user snippets**: - -#. Open :guilabel:`File > Preferences > User Snippets` -#. Enter a name -#. Edit the json file - -Here is an example: - -.. code-block:: json - - { - "image (full)": { - "prefix": "imgf", - "body": [ - ".. image:: $1", - " :class: with-shadow", - " :alt: $2", - " :target: $3", - "$4" - ], - "description": "image with parameters" - } - } - -* You can enter the snippet by typing `imgf`:code: and then TAB -* The $1, $2 etc. mark the places where further TABs will take you. - Use this if extra text needs to be entered - -.. image:: /Images/VsStudio/vscodesnippets2.gif - :class: with-shadow - - -.. index:: reST; PhpStorm - -PhpStorm -======== - -reStructuredText Plugin ------------------------ - -You should activate the `reStructuredText plugin `__ -that will assist you when editing reST -files. In order to activate a plugin, press :kbd:`ctrl + alt + s`, then -select :guilabel:`Plugins`, search for the plugin and enable it (mark -checkbox). - -.. image:: /Images/phpstorm-rest-plugin.png - :class: with-shadow - -If the Plugin is not installed yet, you may have to :guilabel:`Browse -repositories`, select the plugin and click the green :guilabel:`Install` button. - -Some errors in formatting will be pointed out: - -.. image:: /Images/phpstorm-rest-warning.png - :class: with-shadow - -.. _phpstorm-editorconfig: - -EditorConfig Plugin -------------------- - -Additionally, (download) and enable the `EditorConfig `__ -plugin in order to get correct Coding Guideline settings like indent width already defined in -.editorconfig file of documentation project. - -Spellchecking -------------- - -You can add some specific TYPO3 spellings to PhpStorms internal dictionary. -Just place the cursor on the word, click alt-enter and then "Save to dictionary". - -.. image:: /Images/phpstorm-add-to-dictionary.png - :class: with-shadow - - -For more information, see the `Spellchecking `__ -PhpStorm page. - - diff --git a/Documentation/WritingDocForExtension/Index.rst b/Documentation/WritingDocForExtension/Index.rst index 9c71624a..191f81d2 100644 --- a/Documentation/WritingDocForExtension/Index.rst +++ b/Documentation/WritingDocForExtension/Index.rst @@ -61,8 +61,7 @@ Creating extension documentation using the sample manual :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. :ref:`phpstorm-editorconfig` contains further information - for PhpStorm users. (*recommended*) + an editor or IDE. .. code-block:: bash diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index df621f22..0e25008f 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -8,7 +8,7 @@ Workflow #2: "Local editing and rendering with Docker" ====================================================== Using your local machine instead of editing documentation on GitHub has many advantages, it includes -the freedom to choose which IDE you make your changes in (see :ref:`tools-for-editing-rest`) and it also gives you +the freedom to choose which IDE you make your changes in and it also gives you the ability to experiment and preview your changes locally before submitting them for approval. .. rst-class:: bignums-xxl diff --git a/Documentation/WritingReST/Index.rst b/Documentation/WritingReST/Index.rst index 4f2b0544..3b3f3614 100644 --- a/Documentation/WritingReST/Index.rst +++ b/Documentation/WritingReST/Index.rst @@ -21,9 +21,7 @@ the :ref:`writing-rest-introduction` and the general :ref:`format-rest-cgl` first. Also read :ref:`rest-common-pitfalls` in order to avoid common -mistakes with the syntax or make sure to -:ref:`setup your editor or IDE ` correctly -to detect and show errors in the syntax. +mistakes with the syntax. You don't need to read the entire chapter, just lookup the section that is relevant for what you plan to do. From 76a04f632e08229ea9ac113f817538b7f0bcad7a Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 15 Jan 2024 11:01:46 +0100 Subject: [PATCH 08/45] [TASK] Drop the appendix (#358) There is no more usefull information in here. (cherry picked from commit e6d93e2ea5f121113779ca9721f5580300685393) --- Documentation/Appendix/ExampleTocTree/Index.rst | 15 --------------- .../Appendix/ExampleTocTree/Topic1/Index.rst | 14 -------------- .../ExampleTocTree/Topic1/Subtopic1.rst | 8 -------- .../ExampleTocTree/Topic1/Subtopic2.rst | 9 --------- Documentation/Appendix/Index.rst | 11 ----------- Documentation/Appendix/ResourcesForEditors.rst | 17 ----------------- Documentation/Index.rst | 1 - 7 files changed, 75 deletions(-) delete mode 100644 Documentation/Appendix/ExampleTocTree/Index.rst delete mode 100644 Documentation/Appendix/ExampleTocTree/Topic1/Index.rst delete mode 100644 Documentation/Appendix/ExampleTocTree/Topic1/Subtopic1.rst delete mode 100644 Documentation/Appendix/ExampleTocTree/Topic1/Subtopic2.rst delete mode 100644 Documentation/Appendix/Index.rst delete mode 100644 Documentation/Appendix/ResourcesForEditors.rst diff --git a/Documentation/Appendix/ExampleTocTree/Index.rst b/Documentation/Appendix/ExampleTocTree/Index.rst deleted file mode 100644 index eab78fe7..00000000 --- a/Documentation/Appendix/ExampleTocTree/Index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: pair: Examples; Toctree -.. _example-toctree: - -================= -Example *Toctree* -================= - -Select the subchapters in the menu! - -.. toctree:: - :hidden: - - - Topic1/Index diff --git a/Documentation/Appendix/ExampleTocTree/Topic1/Index.rst b/Documentation/Appendix/ExampleTocTree/Topic1/Index.rst deleted file mode 100644 index c35e2678..00000000 --- a/Documentation/Appendix/ExampleTocTree/Topic1/Index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _example-toctree-topic1: - -====== -Topic1 -====== - -.. toctree:: - :hidden: - - - Subtopic1 - Subtopic2 diff --git a/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic1.rst b/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic1.rst deleted file mode 100644 index a4b7b2fb..00000000 --- a/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic1.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _example-toctree-subtopic1: - -========== -Subtopic 1 -========== - diff --git a/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic2.rst b/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic2.rst deleted file mode 100644 index 638a75ed..00000000 --- a/Documentation/Appendix/ExampleTocTree/Topic1/Subtopic2.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _example-toctree-subtopic2: - -========== -Subtopic 2 -========== - - diff --git a/Documentation/Appendix/Index.rst b/Documentation/Appendix/Index.rst deleted file mode 100644 index 2b7cdca7..00000000 --- a/Documentation/Appendix/Index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. include:: /Includes.rst.txt - -======== -Appendix -======== - -.. toctree:: - :hidden: - - ExampleTocTree/Index - ResourcesForEditors diff --git a/Documentation/Appendix/ResourcesForEditors.rst b/Documentation/Appendix/ResourcesForEditors.rst deleted file mode 100644 index 7e2fdfb0..00000000 --- a/Documentation/Appendix/ResourcesForEditors.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. include:: /Includes.rst.txt - -================================== -Information for editing this guide -================================== - -Here, we list some resources that are useful when editing this manual: - - -Resources for this guide -======================== - -* `objects.inv.json `__ -* `warnings.txt `__ - (list of warnings) -* `Issues on GitHub `__ - diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 395129d2..644c85ac 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -140,4 +140,3 @@ What's new in this guide? Sitemap genindex - Appendix/Index From 7d2971afcf5f8ab3ea275a5098df6d30c2e93960 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Thu, 18 Jan 2024 21:21:54 +0100 Subject: [PATCH 09/45] [TASK] Overhaul general file structure section (#361) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Overhaul general file structure section * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Apply suggestions from code review * [TASK] Apply suggestions from code review --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../GeneralConventions/FileStructure.rst | 38 +++++++------------ 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 03bd4257..b96764d1 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -8,9 +8,7 @@ File structure ============== This page explains the general file structure of a TYPO3 documentation that can -be rendered with the :ref:`rendering toolchain `. The toolchain -itself uses a `Sphinx theme `__ -for converting reStructuredText (reST) or Markdown to HTML. +be rendered with the :ref:`rendering toolchain `. .. contents:: Table of Contents: :backlinks: top @@ -18,7 +16,6 @@ for converting reStructuredText (reST) or Markdown to HTML. :depth: 2 :local: - .. _file-structure-general: General @@ -26,31 +23,23 @@ General In order for the documentation to be rendered, you need at least -#. an index file in one of the following locations in weighted order: - - - :file:`Documentation/Index.rst` - - :file:`Documentation/index.rst` - - :file:`Documentation/Index.md` - - :file:`Documentation/index.md` - - :file:`README.rst` - - :file:`README.md` +* A valid :ref:`composer.json ` +* A documentation entry point either for a :ref:`multi-page manual ` + or for the rendering of a :ref:`single README file `. -#. and a theme configuration file under +The following rules are mandatory or your documentation will not render: - - :file:`Documentation/Settings.cfg`. +* :abbr:`reST (reStructured Text)` files MUST have the extension :file:`.rst'. +* Markdown files MUST have the extension :file:`.md'. Further conventions are: -* reST files have the extension **.rst**. -* Markdown files have the extension **.md**. -* Included reST files have the extension **.rst.txt**. -* Use **CamelCase** for directory and file names, - for example: Documentation/GeneralConventions/FileStructure.rst. - -These conventions pave the way for the *full documentation* and the -*single file documentation* style, the first being preferred for several -reasons. - +* :ref:`Included reST files ` SHOULD have the extension + :file:`.rst.txt'. +* Use **CamelCase** for directory and file names, + for example: :file:`Documentation/GeneralConventions/FileStructure.rst`. +* Each directory SHOULD have a file called :file:`Index.rst` it is used as + fallback if a page is not found during switching versions. .. index:: Full documentation .. _full-documentation: @@ -100,7 +89,6 @@ repository, the published documentation and - if available - the TYPO3 Extension Repository (TER) page to guide the reader to the next steps. This could be for example: - .. tabs:: .. group-tab:: With placeholders From e0781b84ecac25dd5078bdd9680f96fb170448a2 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Thu, 18 Jan 2024 21:24:59 +0100 Subject: [PATCH 10/45] [TASK] Overhaul about page (#364) * [TASK] Overhaul about page * Update Documentation/About.rst (cherry picked from commit 8e9f83a49a343bedd4742bceb0ebc5d227751356) --- Documentation/About.rst | 68 +++++++++-------------------------------- 1 file changed, 14 insertions(+), 54 deletions(-) diff --git a/Documentation/About.rst b/Documentation/About.rst index 95a27cf0..976bb444 100644 --- a/Documentation/About.rst +++ b/Documentation/About.rst @@ -1,59 +1,21 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. _about: +.. include:: /Includes.rst.txt +.. highlight:: rst +.. _about: ================ About this guide ================ +This guide was written to help the reader to :ref:`contribute to the official TYPO3 +documentation ` and to :ref:`write documentation for their own +extensions `. -How this guide is structured -============================ +Documentation written in :ref:`reStructured Text ` can be +:ref:`rendered ` using a TYPO3-specific theme and +automatically deployed to +`https://docs.typo3.org`__ by adding a :ref:`Webhook `. -This manual covers writing TYPO3 documentation. This includes, contributing -to official documentation, the core changelog and system extensions and -writing documentation for third party extensions. - -It is more than just documentation: it also lists some conventions, coding -guidelines and provides links to GitHub issues. - - -.. index:: Writing documentation; Getting started -.. _getting-started: -.. _how-to-read-this-guide: - -How to read this guide -====================== - -This manual introduces you to writing TYPO3 documentation. You can read -it cover-to-cover. - -.. tip:: - - Specifically, you might like to look at: - - * :ref:`basic-principles` to familiarize yourself with the structure - * :ref:`conventions` for tips on coding guidelines, spelling etc. - * :ref:`reStructuredText & Sphinx Introduction `. - * Additionally, keep the :ref:`rest-cheat-sheet` handy to look up the syntax. - - -But often, you would like to **jump right in**, start with a specific task -and learn as you go along. In that case, find your task here and start reading: - -* :ref:`how-to-start-docs-extension` if you have an extension and would - like to write documentation for it using the sample extension manual. -* :ref:`docs-contribute-github-method` if you would like to contribute to - the official documentation and need an easy introduction to editing - documentation directly on GitHub. This does not require any development - tools, you just need a browser and a GitHub account. -* :ref:`docs-contribute-git-docker` if you would like to contribute to - the official documentation and are already familiar with Git and Docker -* :ref:`render-documenation-with-docker` if you would like to start with rendering the - documentation locally with Docker. - - -.. _credits: +.. _credits: Credits ======= @@ -64,14 +26,12 @@ Special thanks to Xavier Perseguers, who wrote some of the original texts in the retired TYPO3 Wiki and elsewhere. Some of the texts have been incorporated into this document or at least served as a basis. -Further chapters like -:ref:`rest-common-pitfalls`, :ref:`rest-cheat-sheet`, :ref:`docs-contribute`, -:ref:`basic-principles`, :ref:`writing-doc-for-ext-start` and :ref:`docs-official-how-you-can-help` -were added by Sybille Peters. +Further chapters were added by Sybille Peters. A number of other people have helped by reviewing and refining the text and pointing out missing information. For more contributors, see the -`list of contributors on GitHub for this manual `__. +`list of contributors on GitHub for this manual +`__. We thank everyone for their help and hope that good documentation about writing documentation will make it easier for others to contribute. From 9d4fe69e8d6128360c961a886acdea778c6ea6a4 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Wed, 17 Jan 2024 19:13:31 +0100 Subject: [PATCH 11/45] [TASK] Remove the user Round trip (#363) In my eyes it is not really helpful, to much information, graphs that dont really say much... (cherry picked from commit 7e944fb0173b43235768b156f5d62babdfbddb78) --- Documentation/Index.rst | 1 - Documentation/UserRoundTrip.rst | 349 -------------------------------- 2 files changed, 350 deletions(-) delete mode 100644 Documentation/UserRoundTrip.rst diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 644c85ac..a9483536 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -108,7 +108,6 @@ What's new in this guide? BasicPrinciples GeneralConventions/Index WritingReST/Index - UserRoundTrip .. toctree:: :hidden: diff --git a/Documentation/UserRoundTrip.rst b/Documentation/UserRoundTrip.rst deleted file mode 100644 index ad1c52a7..00000000 --- a/Documentation/UserRoundTrip.rst +++ /dev/null @@ -1,349 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _user-round-trip: - -================= -User's round trip -================= - -When a user wants to find out more about a TYPO3 extension, Composer package or a -standalone manual, they should be provided with information about every aspect of the -project including its rendered documentation, code repository and the Packagist and -TYPO3 Extension Repository (TER) pages. - -It is recommended that you set up a navigation structure that signposts every part of -your project so that users can quickly install, learn and potentially contribute -to your project. This can be achieved by using the native configuration settings. - -.. uml:: - - !include - - skinparam DefaultTextAlignment center - skinparam RectangleBackgroundColor transparent - skinparam RectangleBorderColor transparent - skinparam UsecaseFontColor<< inactive >> #b9b9b9 - skinparam UsecaseBorderColor<< inactive >> #b9b9b9 - skinparam UsecaseBackgroundColor<< inactive >> #FEFEFE - - rectangle "<$typo3>\n Extension / Package / Manual" as typo3actor - usecase "Packagist" as packagist - usecase "VCS repository" as vcsRepository - usecase "Documentation" as documentation - usecase "TYPO3 Extension Repository" as ter - - typo3actor -left-> packagist - typo3actor -right-> vcsRepository - typo3actor -up-> documentation - typo3actor -down-> ter - - packagist <-up-> documentation - documentation <-down-> vcsRepository - vcsRepository <-down-> ter - ter <-up-> packagist - - hide << inactive >> stereotype - -**Table of Contents:** - -.. contents:: - :backlinks: top - :class: compact-list - :depth: 2 - :local: - - -.. _user-round-trip-project-aspects: - -Project aspects -=============== - -Create the round trip by cross-referencing between all aspects of a project as -follows. - - -.. _user-round-trip-documentation-aspect: - -Documentation -------------- - -Guide the user from the documentation to the other aspects by setting these -Sphinx theme configuration properties at :ref:`settings-cfg`: - -.. code-block:: none - - project_home = - project_repository = - project_issues = - -for example for the *News System* extension: - -.. code-block:: none - - project_home = https://extensions.typo3.org/extension/news/ - project_repository = https://github.com/georgringer/news - project_issues = https://github.com/georgringer/news/issues - -and find the links to the other aspects displayed in the footer of the rendered -documentation (see `News System example `__). - -For a Composer package, replace the TER URL with the Packagist URL. For a -standalone manual, replace the TER URL with the documentation URL. - -The Packagist URL is linked indirectly from the TER page and is therefore not -specified in this configuration file. The issues URL is specified, but not -considered part of the round trip, as it usually does not provide a way to link -to other aspects. - - -.. _user-round-trip-vcs-repository-aspect: - -VCS repository --------------- - -Guide the user from the VCS repository page to the other aspects by offering a -table in the :ref:`README file `: - -.. code-block:: md - - | | URL | - |------------------|------------------------------------------------| - | **Repository:** | | - | **Read online:** | | - | **TER:** | | - -for example for the *Mask* extension: - -.. code-block:: md - - | | URL | - |------------------|------------------------------------------------| - | **Repository:** | https://github.com/Gernott/mask | - | **Read online:** | https://docs.typo3.org/p/mask/mask/main/en-us/ | - | **TER:** | https://extensions.typo3.org/extension/mask | - -and find the README file usually displayed by the VCS host below the file list -of the repository (see `Mask example `__). - -For a Composer package, replace the TER URL with the Packagist URL and label it -"Packagist:". For a standalone manual, remove the TER entry. - -The Packagist URL is linked indirectly from the TER page and is therefore not -included in this configuration file. - - -.. _user-round-trip-packagist-aspect: - -Packagist ---------- - -Guide the user from the Packagist page to the other aspects by setting these -:file:`composer.json` configuration values: - -.. code-block:: none - - "homepage": "", - "support": { - "docs": "", - "issues": "", - "source": "" - } - -for example for the *Address List* extension: - -.. code-block:: none - - "homepage": "https://extensions.typo3.org/extension/tt_address", - "support": { - "docs": "https://docs.typo3.org/p/friendsoftypo3/tt-address/main/en-us/", - "issues": "https://github.com/FriendsOfTYPO3/tt_address/issues", - "source": "https://github.com/FriendsOfTYPO3/tt_address" - } - -and find the links to the other aspects shown in the right column of the -Packagist page (see `Address List example `__). - -For a Composer package, replace the TER URL with the Packagist URL. - -The issues URL is specified, but not considered part of the round trip, as it -usually does not provide a way to link to other aspects. - - -.. _user-round-trip-ter-aspect: - -TYPO3 Extension Repository --------------------------- - -Guide the user from the TER page to the other aspects by setting these -configuration values on the -`extension management page `__: - -* **Published on Packagist:** check -* **Composer name of extension:** `` -* **Link to issue tracker:** `` -* **Link to repository:** `` - -for example for the *Static File Cache* extension: - -* **Published on Packagist:** check -* **Composer name of extension:** lochmueller/staticfilecache -* **Link to issue tracker:** \https://github.com/lochmueller/staticfilecache/issues -* **Link to repository:** \https://github.com/lochmueller/staticfilecache - -and find the links to the other aspects presented in the right column of the TER -page (see `Static File Cache example `__). - -The documentation URL is automatically resolved when the documentation is -published on docs.typo3.org. The issues URL is specified, but not considered -part of the round trip, as it usually does not provide a way to link to other -aspects. - - -.. _user-round-trip-project-types: - -Project types -============= - -It depends on your project type whether all aspects can be configured or only a -subset. - - -.. _user-round-trip-typo3-extension-type: - -TYPO3 extension ---------------- - -.. uml:: - - !include - - skinparam DefaultTextAlignment center - skinparam RectangleBackgroundColor transparent - skinparam RectangleBorderColor transparent - skinparam UsecaseFontColor<< inactive >> #b9b9b9 - skinparam UsecaseBorderColor<< inactive >> #b9b9b9 - skinparam UsecaseBackgroundColor<< inactive >> #FEFEFE - - rectangle "<$typo3>\n TYPO3 extension" as typo3actor - usecase "Packagist" as packagist - usecase "VCS repository" as vcsRepository - usecase "Documentation" as documentation - usecase "TYPO3 Extension Repository" as ter - - typo3actor -left-> packagist - typo3actor -right-> vcsRepository - typo3actor -up-> documentation - typo3actor -down-> ter - - packagist <-up-> documentation - documentation <-down-> vcsRepository - vcsRepository <-down-> ter - ter <-up-> packagist - - hide << inactive >> stereotype - -Guide the user to all four aspects of the TYPO3 extension, which is usually -distributed on both TER and Packagist, by configuring: - -#. :ref:`user-round-trip-documentation-aspect` -#. :ref:`user-round-trip-vcs-repository-aspect` -#. :ref:`user-round-trip-ter-aspect` -#. :ref:`user-round-trip-packagist-aspect` - -For example, look at the *Apache Solr* extension and try navigating all four -aspects by simply clicking on a redirect link on each page - starting at the -`Apache Solr TER page `__. - - -.. _user-round-trip-composer-package-type: - -Composer package ----------------- - -.. uml:: - - !include - - skinparam DefaultTextAlignment center - skinparam RectangleBackgroundColor transparent - skinparam RectangleBorderColor transparent - skinparam UsecaseFontColor<< inactive >> #b9b9b9 - skinparam UsecaseBorderColor<< inactive >> #b9b9b9 - skinparam UsecaseBackgroundColor<< inactive >> #FEFEFE - - rectangle "<$typo3>\n Composer package" as typo3actor - usecase "Packagist" as packagist - usecase "VCS repository" as vcsRepository - usecase "Documentation" as documentation - usecase "TYPO3 Extension Repository" << inactive >> as ter - - typo3actor -left-> packagist - typo3actor -right-> vcsRepository - typo3actor -up-> documentation - typo3actor -[hidden]down-> ter - - packagist <-up-> documentation - documentation <-down-> vcsRepository - vcsRepository <-[hidden]down-> ter - ter <-[hidden]up-> packagist - - hide << inactive >> stereotype - -A Composer package that is not a TYPO3 extension is usually distributed only on -Packagist. Therefore, guide the user to three aspects of the package by -configuring: - -#. :ref:`user-round-trip-documentation-aspect` -#. :ref:`user-round-trip-vcs-repository-aspect` -#. :ref:`user-round-trip-packagist-aspect` - -For example, examine the *TYPO3 Console* package and try navigating through its -three aspects by just clicking on a redirecting link on each page - starting at -the `TYPO3 Console Packagist page `__. - - -.. _user-round-trip-standalone-manual-type: - -Standalone manual ------------------ - -.. uml:: - - !include - - skinparam DefaultTextAlignment center - skinparam RectangleBackgroundColor transparent - skinparam RectangleBorderColor transparent - skinparam UsecaseFontColor<< inactive >> #b9b9b9 - skinparam UsecaseBorderColor<< inactive >> #b9b9b9 - skinparam UsecaseBackgroundColor<< inactive >> #FEFEFE - - rectangle "<$typo3>\n Standalone manual" as typo3actor - usecase "Packagist" << inactive >> as packagist - usecase "VCS repository" as vcsRepository - usecase "Documentation" as documentation - usecase "TYPO3 Extension Repository" << inactive >> as ter - - typo3actor -[hidden]left-> packagist - typo3actor -right-> vcsRepository - typo3actor -up-> documentation - typo3actor -[hidden]down-> ter - - packagist <-[hidden]up-> documentation - documentation <-down-> vcsRepository - vcsRepository <-[hidden]down-> ter - ter <-[hidden]up-> packagist - - hide << inactive >> stereotype - -A standalone manual, i.e. a tutorial, guide or reference, is usually not -provided in a store. Therefore, guide the user to two aspects of the manual by -configuring: - -#. :ref:`user-round-trip-documentation-aspect` -#. :ref:`user-round-trip-vcs-repository-aspect` - -For example, take a look at the *Getting Started* tutorial and try navigating -between the two aspects by simply clicking on a redirecting link on each page - -starting at the -`Getting Started documentation `__. From ab8be6bac1c09b98d434464059e74dceb920ed23 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 15 Jan 2024 19:45:48 +0100 Subject: [PATCH 12/45] [TASK] Drop General "How to use GitHub" information (#359) * [TASK] Drop General "How to use GitHub" information Move specific information for our organization to the according chapters * [TASK] Use TYPO3 Explained as example (cherry picked from commit 9a43c59b9e875cb61c1f90ee0830456581dec0b0) --- Documentation/GitHub/Index.rst | 209 ------------------ Documentation/Index.rst | 1 - .../WritingDocsOfficial/HowYouCanHelp.rst | 67 +++++- 3 files changed, 63 insertions(+), 214 deletions(-) delete mode 100644 Documentation/GitHub/Index.rst diff --git a/Documentation/GitHub/Index.rst b/Documentation/GitHub/Index.rst deleted file mode 100644 index 51109ea7..00000000 --- a/Documentation/GitHub/Index.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: GitHub -.. _work-with-github: -.. _useful-links: - -======================= -How to work with GitHub -======================= - - -.. tip:: **Looking for help on 'How to edit'?** - - Please head over to page :ref:`docs-contribute-github-method`. - - -.. index:: GitHub; Repository -.. _github-find-a-repository: - -How to find a GitHub repository -=============================== - -The source for every manual on docs.typo3.org (for example this manual :ref:`start` or -:ref:`t3coreapi:start`) is contained in a GitHub repository. - -In the repository, you can find the source files, but also the issues and pull requests. - -The repositories of the official manuals are all included in the organization -`TYPO3-Documentation `__. - -There, you can browse through the repositories or search for a specific -repository: - -.. image:: /Images/github-repo-search.png - :class: with-shadow - -Alternatively, on any rendered page on docs.typo3.org (for example, this page), -you can find the link :guilabel:`Repository` in the footer on the bottom -of the page. - - -.. index:: GitHub; Notifications -.. _github-get-notifications: - -Get notifications from GitHub -============================= - -You can get notifications for activity in a repository (for example new pull requests or -issues) by **watching** the repository: - - -#. Find the repository you would like to watch, see :ref:`github-find-a-repository` - For example, go to the repository for `TYPO3 Explained `__ -#. Click on the **Watch** button on the top of the page - -.. image:: /Images/watch-repo.gif - :class: with-shadow - - -.. index:: GitHub; Issues -.. _links-github-issues: - -Find issues -=========== - -Pick an issue for a topic you are familiar with and try to fix it. Some of the -issues address a problem, some are enhancements where new text needs to be -written. - -You can look at the open issues of a manual you are familiar with, pick one -and fix the problem. - -For example: - -* `Issues for this guide "Writing Documentation" - `__ -* `Issues for "Getting Started Tutorial" - `__ - - -Find issues for a specific manual ---------------------------------- - -From docs.typo3.org: - To find the issues for a specific manual click on the link - :guilabel:`Issues` in the footer on the bottom of the page. - -From the repository on GitHub: - If you have already located the repository on GitHub, you can find the Issues - by clicking on the :guilabel:`Issues` tab: - - .. image:: /Images/github-issues.png - :class: with-shadow - -From the list of repositories in `TYPO3-Documentation `__: - Look for the exclamation mark (!) issues icon: - - .. image:: /Images/github-list-issues.png - :class: with-shadow - - -.. _github-good-first-issue: -.. _useful-links-for-contributors: - -Links to GitHub issues ----------------------- - -Here are some links to GitHub issues in `TYPO3-Documentation `__. - -.. important:: - - GitHub will show a 404 page if you are not logged in following these links! - So, remember to log in first! - -For new contributors: - -* `Good first issues `__ (Link to GitHub) - -For contributors: - -* `All open, unassigned issues (without team, theme etc.) `__ (Link to GitHub) - -For team members and advanced contributors: - -* `All open issues - `__ (Link to GitHub) -* `All open, unassigned issues - `__ (Link to GitHub) - -The Docker image for rendering is in the organization **t3docs** (instead of TYPO3-Documentation): - -* `All open issues in t3docs `__ (Link to GitHub) - - -.. index:: GitHub; Issue solving -.. _github-solve-issue: - -Solve an Issue -============== - -When you solve an existing issue from GitHub, it is good practice to refer to it in the commit message. - -For example, write: - -.. code-block:: none - - Resolves: #12 - - -This will automatically close the issue and a link to the issue is displayed in the commit message and -pull request on GitHub. - -.. seealso:: - - :ref:`general-conventions-commit-messages` - - - -.. index:: - pair: GitHub; Pull requests - Pull requests - PR - see: PR; Pull requests -.. _github-pull-requests: - -Find Pull Requests -================== - -.. important:: - - GitHub will show a 404 page if you are not logged in following these links! - So, remember to log in first! - - -Anyone is welcome to review open pull requests! - -In **TYPO3-Documentation**: - -* `Open pull requests `__ (Link to GitHub) - -In **t3docs** (Docker image): - -* `Open pull requests `__ (Link to GitHub) - -About reviewing pull requests, you can look in the GitHub help pages: - -.. seealso:: - - * `About pull request reviews `__ (GitHub) - * `Commenting on a pull request `__ (GitHub) - -.. tip:: - - If you are reviewing a pull request and want to leave comments, make sure to - `mark the line `__ - in the PR. - - -Find pull requests that require my attention -============================================ - -When another contributor creates their own pull request, they might ask you to review -their change by assigning you to the pull request as an assignee. - -To review all requests that are assigned to you, select :guilabel:`Pull requests` from the main navigation bar -followed by :guilabel:`Review requests`. - -.. image:: /Images/github-review-requests.png - :class: with-shadow diff --git a/Documentation/Index.rst b/Documentation/Index.rst index a9483536..a8e37f8e 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -117,7 +117,6 @@ What's new in this guide? WritingDocForExtension/Index WritingDocsOfficial/Index RenderingDocs/Index - GitHub/Index .. toctree:: :hidden: diff --git a/Documentation/WritingDocsOfficial/HowYouCanHelp.rst b/Documentation/WritingDocsOfficial/HowYouCanHelp.rst index 36fce114..725dce6a 100644 --- a/Documentation/WritingDocsOfficial/HowYouCanHelp.rst +++ b/Documentation/WritingDocsOfficial/HowYouCanHelp.rst @@ -29,12 +29,57 @@ for a walkthrough. .. _how-you-can-help-fix-issues: +.. _links-github-issues: Fix issues ========== -See :ref:`links-github-issues`. As a new contributor, specifically look at issues -with the label :ref:`good first issue `. +Pick an issue for a topic you are familiar with and try to fix it. Some of the +issues address a problem, some are enhancements where new text needs to be +written. + +You can look at the open issues of a manual you are familiar with, pick one +and fix the problem. + +For example: + +* `Issues for "TYPO3 Explained" + `__ +* `Issues for "Getting Started Tutorial" + `__ + + +.. _github-good-first-issue: +.. _useful-links-for-contributors: + +Links to GitHub issues +---------------------- + +Here are some links to GitHub issues in `TYPO3-Documentation `__. + +.. important:: + + GitHub will show a 404 page if you are not logged in following these links! + So, remember to log in first! + +For new contributors: + +* `Good first issues `__ (Link to GitHub) + +For contributors: + +* `All open, unassigned issues (without team, theme etc.) `__ (Link to GitHub) + +For team members and advanced contributors: + +* `All open issues + `__ (Link to GitHub) +* `All open, unassigned issues + `__ (Link to GitHub) + +The Docker image for rendering is in the organization **t3docs** (instead of TYPO3-Documentation): + +* `All open issues in t3docs `__ (Link to GitHub) .. _how-you-can-help-review-pr: @@ -42,12 +87,26 @@ with the label :ref:`good first issue `. Review pull requests ==================== -:ref:`Find an open pull request ` and review it. - Some pull requests make changes in documentation describing an aspect of TYPO3 you may know well. Help in this area is very much appreciated! +.. important:: + + GitHub will show a 404 page if you are not logged in following these links! + So, remember to log in first! + + +Anyone is welcome to review open pull requests! + +In **TYPO3-Documentation**: + +* `Open pull requests `__ (Link to GitHub) + +In **t3docs** (Docker image): + +* `Open pull requests `__ (Link to GitHub) + .. _how-you-can-help-write-new-content: From 816d788e29dc5807f1395574df7f97ef0c6bfe30 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 15 Jan 2024 19:45:37 +0100 Subject: [PATCH 13/45] [TASK] Remove orphaned pages and warnings (#362) (cherry picked from commit 13bbda048aa57694822e5507685dbdfeae1ee195) --- Documentation/Changes.rst | 98 ------------------- Documentation/GettingStarted.rst | 3 - Documentation/Maintainers/Index.rst | 1 + Documentation/WritingContent/Guide.rst | 11 --- .../WritingDocForExtension/Introduction.rst | 13 --- .../WritingDocsOfficial/Quickstart.rst | 9 -- .../WritingDocsOfficial/WorkflowMethods.rst | 12 --- 7 files changed, 1 insertion(+), 146 deletions(-) delete mode 100644 Documentation/Changes.rst delete mode 100644 Documentation/GettingStarted.rst delete mode 100644 Documentation/WritingContent/Guide.rst delete mode 100644 Documentation/WritingDocForExtension/Introduction.rst delete mode 100644 Documentation/WritingDocsOfficial/Quickstart.rst delete mode 100644 Documentation/WritingDocsOfficial/WorkflowMethods.rst diff --git a/Documentation/Changes.rst b/Documentation/Changes.rst deleted file mode 100644 index 06cd793a..00000000 --- a/Documentation/Changes.rst +++ /dev/null @@ -1,98 +0,0 @@ -:orphan: - -.. include:: /Includes.rst.txt -.. index:: ! Changes -.. _changes: - -======= -Changes -======= - - -.. index:: - Changes; Master branches to main - Git; Branch main - Git; Branch master (outdated) -.. _tip-branches-main: -.. rst-class:: panel panel-default - -[IMPORTANT] Change master branches to main -========================================== - - -This is important if you are using the -:ref:`Local Git / Docker workflow ` and -are working on already existing fork / clone. - -Each documentation project has a main (or default) branch. This usually -corresponds to the latest released TYPO3 version. -For some official manuals, the main branch had been `master`. -We now changed this, so that `main` is the main branch for all manuals. - -**In the future, you should make sure to always work on branch main.** - -When you create a new fork and clone, this should not be a problem. - -But, when you are using a local repository that you cloned a while ago, -make sure to get the latest changes and work on `main` in the future. - -.. rst-class:: bignums - - 1. Check your branches: - - .. code-block:: bash - - git branch - - or - - .. code-block:: bash - - git branch -a - - 2. Setup upstream remote - - This will get you changes from the original repository, not your fork. - - .. code-block:: bash - - git remote add upstream git@github.com:TYPO3-Documentation/.git - - 3. Fetch from remote: - - .. code-block:: bash - - git fetch upstream - - 4. Checkout main branch: - - .. code-block:: bash - - git checkout main - - -.. index:: - Changes; Extension manual migration - Extensions; Manual migration -.. _tip-ext-new-doc-server: -.. rst-class:: panel panel-default - -[IMPORTANT] Extension manual migration to the new infrastructure -================================================================ - -Because of the -`move to the new documentation server `__, -a valid composer.json -and a webhook is now mandatory for extensions, in order to automatically be -rendered on the documentation server. - -Read more: :ref:`migrate` - -If you see the following on the rendered page of your extension, it has not -yet been rendered with the new mechanism: - -.. figure:: /Images/docs_deprecation.png - :class: with-shadow - :alt: Deprecation message on rendered extension documentation page - - Deprecation message on rendered extension documentation page diff --git a/Documentation/GettingStarted.rst b/Documentation/GettingStarted.rst deleted file mode 100644 index 5f3754e2..00000000 --- a/Documentation/GettingStarted.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -This page was moved: :ref:`getting-started`. diff --git a/Documentation/Maintainers/Index.rst b/Documentation/Maintainers/Index.rst index 96fd4ad4..c74ed70d 100644 --- a/Documentation/Maintainers/Index.rst +++ b/Documentation/Maintainers/Index.rst @@ -10,5 +10,6 @@ For maintainers :maxdepth: 1 BackportChanges + Changelog NewMajorCoreVersion Tools diff --git a/Documentation/WritingContent/Guide.rst b/Documentation/WritingContent/Guide.rst deleted file mode 100644 index a73c3f01..00000000 --- a/Documentation/WritingContent/Guide.rst +++ /dev/null @@ -1,11 +0,0 @@ -:orphan: - -.. include:: /Includes.rst.txt -.. highlight:: rst -.. todo:: Add information about writing a guide - -.. _writing-guide: - -=============== -Writing a guide -=============== diff --git a/Documentation/WritingDocForExtension/Introduction.rst b/Documentation/WritingDocForExtension/Introduction.rst deleted file mode 100644 index 855a956c..00000000 --- a/Documentation/WritingDocForExtension/Introduction.rst +++ /dev/null @@ -1,13 +0,0 @@ -:orphan: - -.. include:: /Includes.rst.txt -.. highlight:: rst - - - -===================== -Introduction & Basics -===================== - - - diff --git a/Documentation/WritingDocsOfficial/Quickstart.rst b/Documentation/WritingDocsOfficial/Quickstart.rst deleted file mode 100644 index 12bd92ba..00000000 --- a/Documentation/WritingDocsOfficial/Quickstart.rst +++ /dev/null @@ -1,9 +0,0 @@ -:orphan: - -.. include:: /Includes.rst.txt - -===== -Moved -===== - -This page was moved to :ref:`docs-contribute-git-docker`. \ No newline at end of file diff --git a/Documentation/WritingDocsOfficial/WorkflowMethods.rst b/Documentation/WritingDocsOfficial/WorkflowMethods.rst deleted file mode 100644 index f7ecbca4..00000000 --- a/Documentation/WritingDocsOfficial/WorkflowMethods.rst +++ /dev/null @@ -1,12 +0,0 @@ -:orphan: - -.. include:: /Includes.rst.txt -.. highlight:: rst - - -============================ -Overview of Workflow methods -============================ - -See :ref:`docs-official-workflow-methods` for an overview of workflow -methods. From de1e4d1a571ae39ae06aab6457eb55be3ecea7fa Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 21 Jan 2024 11:38:06 +0100 Subject: [PATCH 14/45] [BUGFIX] Remove warnings (#368) Co-authored-by: lina.wolf --- Documentation/About.rst | 2 +- Documentation/BasicPrinciples.rst | 2 -- Documentation/Maintainers/Tools.rst | 4 ++-- Documentation/WritingDocsOfficial/LocalEditing.rst | 2 +- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/Documentation/About.rst b/Documentation/About.rst index 976bb444..0f5baa79 100644 --- a/Documentation/About.rst +++ b/Documentation/About.rst @@ -13,7 +13,7 @@ extensions `. Documentation written in :ref:`reStructured Text ` can be :ref:`rendered ` using a TYPO3-specific theme and automatically deployed to -`https://docs.typo3.org`__ by adding a :ref:`Webhook `. +https://docs.typo3.org by adding a :ref:`Webhook `. .. _credits: diff --git a/Documentation/BasicPrinciples.rst b/Documentation/BasicPrinciples.rst index 4f542899..44b30002 100644 --- a/Documentation/BasicPrinciples.rst +++ b/Documentation/BasicPrinciples.rst @@ -135,8 +135,6 @@ A guide is a manual. Guides offer advice on **how best to achieve a given task**. They are goal oriented. -:ref:`Read more ... ` - .. index:: TYPO3 documentation; Reference .. _doc-type-reference: diff --git a/Documentation/Maintainers/Tools.rst b/Documentation/Maintainers/Tools.rst index 85661a66..d428e549 100644 --- a/Documentation/Maintainers/Tools.rst +++ b/Documentation/Maintainers/Tools.rst @@ -1,7 +1,7 @@ .. include:: /Includes.rst.txt .. highlight:: shell .. index:: Changes; Backporting -.. _backport-changes: +.. _tools_of_the_documentation_team: =============================== Tools of the Documentation Team @@ -20,7 +20,7 @@ https://github.com/TYPO3-Documentation/DocsTypo3Org-Homepage/blob/main/WebRootRe As this is a pure HTML file, we currently keep the content in this rst file: https://github.com/TYPO3-Documentation/DocsTypo3Org-Homepage/blob/main/Documentation/Home/ApiTypo3Org.rst -locally render it, +locally render it, then update :file:`WebRootResources-api.typo3.org/index.html` with the rendered output. diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 0e25008f..314b1f9d 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -63,7 +63,7 @@ the ability to experiment and preview your changes locally before submitting the #. Make sure the repository is up-to-date by pulling from upstream as described in :ref:`contribute-edit-locally-more-changes`. - #. Always branch from `main` (see also :ref:`tip-branches-main`). + #. Always branch from `main`. If you are checked in to a feature branch, switch back to `main` first: From 5789ddc7008ba8a8d3d879ec5c53167153055a78 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sun, 21 Jan 2024 11:43:32 +0100 Subject: [PATCH 15/45] [TASK] Reduce single file documentation / README (#365) prune unnecessary information. --- .../GeneralConventions/FileStructure.rst | 156 +----------------- 1 file changed, 7 insertions(+), 149 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index b96764d1..017b4bab 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -651,31 +651,15 @@ the toolchain log file at :file:`Documentation-GENERATED-temp/Result/project/0.0 .. index:: Single file documentation .. _single-file-documentation: -Single file documentation -========================= +Single file documentation (README) +================================== -This setup is not recommended, but can be handy for those who want to publish -their documentation on docs.typo3.org and want to keep their mono -:file:`README.rst` documentation style for now. +For third-party TYPO3 extensions that do not require extended documentation +you can also publish a :file:`README.rst` or :file:`README.md` to +https://docs.typo3.org/ -This structure allows the author to minimize effort by maintaining a single -documentation file that is interpreted simultaneously by the VCS host -and the Sphinx theme. On the other hand, the author only has -the reduced set of content elements supported by the former, rather than using -the theme's rich selection of :ref:`custom content elements `. - -Of course, you can also use a :file:`README.md` instead of a :file:`README.rst` -file if you prefer its syntax. - -.. code-block:: none - - . - ├── README.rst - └── Documentation - └── Settings.cfg - - -.. _single-file-documentation-readme-rst: +For this workflow the :file:`README(.rst/.md)` MUST be situated in the +extension's root folder. The :file:`Documentation/' folder can then be omitted. :file:`README.rst` ------------------ @@ -695,129 +679,3 @@ to the next steps, for example .. group-tab:: Markdown .. include:: /CodeSnippets/FileStructure/ReadmeMdStandalone.rst.txt - - -For more details, see the explanation of :ref:`README.rst ` in the -full documentation section. - - -.. _single-file-documentation-settings-cfg: - -:file:`Documentation/Settings.cfg` ----------------------------------- - -This file contains the configuration for the Sphinx theme. See the explanation -of :ref:`Settings.cfg ` in the full documentation section for more -details. - -.. note:: - - You can reduce the single file documentation even further by omitting the - Settings.cfg - which is even less recommended, but works. All Sphinx - theme variables will then fall back to their default values, e.g. the project - title will then be "The Project's Title" and the release version "0.0.0". - - -.. _examples: - -Examples -======== - -These are some good examples of TYPO3 full and single file documentation in the -wild. - - -.. _examples-official-typo3-manuals: - -Official TYPO3 manuals ----------------------- - -.. table:: - :widths: 25, 75 - - ========================= ================================================== - Project Links - ========================= ================================================== - TSconfig Reference (full) `README.rst `__ | - `Settings.cfg `__ | - `Index.rst `__ | - `Includes.rst.txt `__ | - `Read online `__ - ========================= ================================================== - - -.. _examples-typo3-system-extension-documentation: - -TYPO3 system extension documentation ------------------------------------- - -.. table:: - :widths: 25, 75 - - =========================== ================================================ - Project Links - =========================== ================================================ - Import / Export (full) `README.rst `__ | - `Settings.cfg `__ | - `Index.rst `__ | - `Includes.rst.txt `__ | - `Read online `__ - =========================== ================================================ - - -.. _examples-typo3-third-party-extension-documentation: - -TYPO3 third-party extension documentation ------------------------------------------ - -.. table:: - :widths: 25, 75 - - ======================== =================================================== - Project Links - ======================== =================================================== - Extension Builder (full) `README.rst `__ | - `Settings.cfg `__ | - `Index.rst `__ | - `Includes.rst.txt `__ | - `Read online `__ - ------------------------ --------------------------------------------------- - Make (single) `README.md `__ | - `Settings.cfg `__ | - `Read online `__ - ======================== =================================================== - - -.. _examples-php-application-documentation: - -PHP application documentation ------------------------------ - -.. table:: - :widths: 25, 75 - - ================== ========================================================= - Project Links - ================== ========================================================= - Surf (full) `README.md `__ | - `Settings.cfg `__ | - `Index.rst `__ | - `Includes.txt `__ | - `Read online `__ - ------------------ --------------------------------------------------------- - Tailor (single) `README.md `__ | - `Read online `__ - ================== ========================================================= - -.. seealso:: - - Although it is possible to write every single line of a full documentation - from scratch, the TYPO3 community provides tools to support you: - - * A `sample manual `__ - is available to be immediately copied into your own extension. - * The `Extension Builder `__ - optionally generates a sample documentation together with the extension - skeleton. - * TYPO3 Core developers use the `ReST Helper `__ - to kickoff a new TYPO3 changelog entry. From 90b9417e4b9982f3dafb8007025ecc97f8e09d19 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sun, 21 Jan 2024 18:36:04 +0100 Subject: [PATCH 16/45] [TASK] Introduce Makefile and command 'make docs' (#370) * [TASK] Introduce Makefile and command 'make docs' This is more convenient then having to copy-paste the command all the time * Update CONTRIBUTING.rst --- CONTRIBUTING.rst | 13 +++++++++++-- Makefile | 11 +++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) create mode 100644 Makefile diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b15bd5a9..ad7d2091 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -5,6 +5,15 @@ Contributing Information About Contributing to This Manual ============================================= +Local rendering +--------------- + +You can render this manual locally if you have `Docker ` +and `make ` installed on your local +machine:: + + make docs + Create Issues ------------- @@ -21,10 +30,10 @@ Make changes (create pull requests) `rendered page `__, just click on "Edit me on GitHub". * Step-by-step walkthrough of making a change by `Editing Directly on GitHub - `__ + `__ (this requires only a browser) * Step-by-step walkthrough of `Local Editing and Rendering with Docker - `__ + `__ (this requires knowledge of Git and Docker) * See `Writing Documentation `__ for further diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..325b94fd --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +.PHONY: help +help: ## Displays this list of targets with descriptions + @echo "The following commands are available:\n" + @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' + + +.PHONY: docs +docs: ## Generate projects docs (from "Documentation" directory) + mkdir -p Documentation-GENERATED-temp + + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation From c2a2db984da18f67bbb010a038cf8dc89b0575a1 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Tue, 23 Jan 2024 07:06:29 +0100 Subject: [PATCH 17/45] [TASK] Move best practises for additonal readme files (#369) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Move best practises for additonal readme files * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/ReadmeFile.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../GeneralConventions/FileStructure.rst | 123 ++---------------- .../GeneralConventions/ReadmeFile.rst | 95 ++++++++++++++ 2 files changed, 105 insertions(+), 113 deletions(-) create mode 100644 Documentation/GeneralConventions/ReadmeFile.rst diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 017b4bab..84c3cd88 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -38,7 +38,7 @@ Further conventions are: :file:`.rst.txt'. * Use **CamelCase** for directory and file names, for example: :file:`Documentation/GeneralConventions/FileStructure.rst`. -* Each directory SHOULD have a file called :file:`Index.rst` it is used as +* Each directory SHOULD have a file named :file:`Index.rst` it is used as fallback if a page is not found during switching versions. .. index:: Full documentation @@ -47,129 +47,26 @@ Further conventions are: Full documentation ================== -This is the recommended setup and is commonly used in the official TYPO3 manuals -and extension documentation. +To render a complete documentation manual you need a folder called +:file:`Documentation` with at least a reStructured Text file as entry point named +:file:`Documentation\Index.rst` and a configuration file called +:file:`Documentation\guides.xml`. Add more files as needed. -This structure splits the documentation for the VCS host (README.rst) and the -Sphinx theme (Documentation/) and allows full use of a continuously expanded set -of :ref:`custom content elements `, like UML diagrams, which are -only supported by the theme. This structure allows to add multiple pages to -the documentation and build a full page tree. - -The Settings.cfg configuration file allows you to set theme variables, i.e. the -project title, release version and the like. - -Of course, you can also use a README.md instead of a README.rst file as both -markup languages are supported by the common VCS hosts. +You can keep a :file:`README.md` or :file:`README.rst` file with basic +information and a link to the published manual in the root folder of the extension. These files will be commonly +displayed on GitHub and GitLab. .. code-block:: none . + ├── composer.json ├── README.rst └── Documentation - ├── genindex.rst - ├── Includes.rst.txt + ├── guides.xml ├── Index.rst - ├── Settings.cfg ├── Sitemap.rst └── .. - -.. index:: File structure; README.rst, README.rst -.. _readme-rst: -.. _about-file: - -Entry point: :file:`README.rst` -------------------------------- - -Full documentation contains both a README.rst and a Documentation/Index.rst -file. To avoid redundancy in both places, the README.rst in this case usually -contains only a summary and links to all aspects of the project, i.e. the VCS -repository, the published documentation and - if available - the TYPO3 Extension -Repository (TER) page to guide the reader to the next steps. This could be for -example: - -.. tabs:: - - .. group-tab:: With placeholders - - .. include:: /CodeSnippets/FileStructure/ReadmeRst.rst.txt - - .. group-tab:: Third party extension - - .. include:: /CodeSnippets/FileStructure/Examples/IndexRst.rst.txt - - .. group-tab:: System extension - - .. include:: /CodeSnippets/FileStructure/Dashboard/IndexRst.rst.txt - - .. group-tab:: Official manual - - .. include:: /CodeSnippets/FileStructure/GettingStarted/IndexRst.rst.txt - - .. group-tab:: Markdown - - .. include:: /CodeSnippets/FileStructure/ReadmeMd.rst.txt - - -.. _readme-rst-badges: - -Badges -^^^^^^ - -Point out interesting statistics of your extension or package in the *badges* -placeholder, which should include the latest release version, the total and -monthly download rate and the supported TYPO3 versions: - -.. tabs:: - - .. group-tab:: Rest - - .. include:: /CodeSnippets/FileStructure/Badges.rst.txt - - .. group-tab:: Markdown - - .. include:: /CodeSnippets/FileStructure/BadgesMd.rst.txt - - -Remove this field if the project is no extension or package. - - -.. _readme-rst-project: - -Project -^^^^^^^ - -The *project* placeholder contains the title of the project. - -Common values are in the official TYPO3 manuals - -#. ` Guide`, e.g. "Installation and Upgrade Guide", - for collections of articles on a specific topic -#. ` Reference`, e.g. "TCA Reference", - for a complete encyclopedia -#. ` Tutorial`, e.g. "Getting Started Tutorial", - for collections of tutorials on a specific topic - -and in TYPO3 system and third-party extensions - -* `TYPO3 extension `, e.g. "TYPO3 extension \`\`extbase\`\`" and - "TYPO3 extension \`\`mask\`\`". - - -.. _readme-rst-abstract: - -Abstract -^^^^^^^^ - -The *abstract* placeholder contains a short and precise description of the -project with as many keywords as possible in as few sentences as possible. It -helps the decision maker to quickly decide whether the project is worth -considering and whether or not to read the full documentation. It should be -aligned with the abstract of Index.rst and - if available - the description -fields of :file:`ext_emconf.php` and :file:`composer.json`. - - .. index:: File structure; Documentation/Index.rst, Index.rst .. _index-rst: .. _start-file: diff --git a/Documentation/GeneralConventions/ReadmeFile.rst b/Documentation/GeneralConventions/ReadmeFile.rst new file mode 100644 index 00000000..06339544 --- /dev/null +++ b/Documentation/GeneralConventions/ReadmeFile.rst @@ -0,0 +1,95 @@ + +.. index:: File structure; README.rst, README.rst +.. _readme-rst: +.. _about-file: + +======================================= +:file:`README.rst` or :file:`README.md` +======================================= + +Full documentation contains both a :file:`README.rst` and a :file:`Documentation/Index.rst` +file. To avoid redundancy in both places, the :file:`README.rst` in this case usually +contains only a summary and links to all aspects of the project, i.e. the :abbr:`VCS (Version Control System)` +repository, the published documentation and - if available - the TYPO3 Extension +Repository (TER) page to guide the reader to the next steps. This could be for +example: + +.. tabs:: + + .. group-tab:: With placeholders + + .. include:: /CodeSnippets/FileStructure/ReadmeRst.rst.txt + + .. group-tab:: Third-party extension + + .. include:: /CodeSnippets/FileStructure/Examples/IndexRst.rst.txt + + .. group-tab:: System extension + + .. include:: /CodeSnippets/FileStructure/Dashboard/IndexRst.rst.txt + + .. group-tab:: Official manual + + .. include:: /CodeSnippets/FileStructure/GettingStarted/IndexRst.rst.txt + + .. group-tab:: Markdown + + .. include:: /CodeSnippets/FileStructure/ReadmeMd.rst.txt + + +.. _readme-rst-badges: + +Badges +====== + +Point out interesting statistics of your extension or package in the *badges* +placeholder, which may include the latest release version, the total and +monthly download rate and the supported TYPO3 versions: + +.. tabs:: + + .. group-tab:: reStructured Text + + .. include:: /CodeSnippets/FileStructure/Badges.rst.txt + + .. group-tab:: Markdown + + .. include:: /CodeSnippets/FileStructure/BadgesMd.rst.txt + + +Remove this field if the project is no extension or package. + + +.. _readme-rst-project: + +Project +======= + +The *project* placeholder contains the title of the project. + +Common values are, for example, in the official TYPO3 manuals + +#. ` Guide`, e.g. "Installation and Upgrade Guide", + for collections of articles on a specific topic +#. ` Reference`, e.g. "TCA Reference", + for a complete encyclopedia +#. ` Tutorial`, e.g. "Getting Started Tutorial", + for collections of tutorials on a specific topic + +and in TYPO3 system and third-party extensions + +* `TYPO3 extension `, e.g. "TYPO3 extension \`\`extbase\`\`" and + "TYPO3 extension \`\`mask\`\`". + + +.. _readme-rst-abstract: + +Abstract +======== + +The *abstract* placeholder contains a short and precise description of the +project with as many keywords as possible in as few sentences as possible. It +helps the decision maker to quickly decide whether the project is worth +considering and whether or not to read the full documentation. It should be +aligned with the abstract of :file:`Index.rst` and - if available - the description +fields of :file:`ext_emconf.php` and :file:`composer.json`. From ca8a5fcbc4517d07b0e54ee8a13b6409b156f7ab Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 10:45:35 +0100 Subject: [PATCH 18/45] [TASK] Overhaul Startpage and menu / toctree configuration (#371) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Overhaul Startpage and menu / toctree configuration * [TASK] Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/GeneralConventions/FileStructure.rst * Update Documentation/GeneralConventions/FileStructure.rst * Update Documentation/GeneralConventions/FileStructure.rst * Update Documentation/GeneralConventions/FileStructure.rst * Update Documentation/GeneralConventions/FileStructure.rst --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../GeneralConventions/FileStructure.rst | 186 ++++++------------ 1 file changed, 55 insertions(+), 131 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 84c3cd88..8a3f85c0 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -71,113 +71,46 @@ displayed on GitHub and GitLab. .. _index-rst: .. _start-file: -Startpage: :file:`Documentation/Index.rst` ------------------------------------------- +Start page: :file:`Documentation/Index.rst` +------------------------------------------- -The documentation index file at :file:`Documentation/Index.rst` is the starting +The documentation start page (:file:`Documentation/Index.rst`) is the entry point of the main documentation. It usually contains general information about the manual, a summary of its purpose and a table of contents that refers to -further pages. Besides these basic parts of this file, it includes - like any -other reST file - the reST style file :file:`Includes.rst.txt`: - -.. tabs:: - - .. group-tab:: With placeholders - - .. include:: /CodeSnippets/FileStructure/IndexRst.rst.txt - - .. group-tab:: Third party extension - - .. include:: /CodeSnippets/FileStructure/Examples/IndexRst.rst.txt - - .. group-tab:: System extension - - .. include:: /CodeSnippets/FileStructure/Dashboard/IndexRst.rst.txt - - .. group-tab:: Official manual - - .. include:: /CodeSnippets/FileStructure/GettingStarted/IndexRst.rst.txt - -All variables of the `|name|` pattern are automatically replaced by the Sphinx -theme, partly from Settings.cfg, partly by internal calculations. For more -information about all available variables, see the -:doc:`Replacements ` chapter of the Sphinx -theme documentation. - -The placeholders of pattern `` must be replaced manually by the author of -the documentation: +further pages. -The startpage should contain an anchor target :rst:`.. _start:` above its +The start page should contain an anchor target :rst:`.. _start:` above its document title. This way you can link to a documents start page by: .. code-block:: rst See :ref:`TYPO3 Explained `. +If your manual has more pages then this start page it must contain a table of content +directive called :rst:`.. toctree::`. The `toctree` on the start page +defines which pages will be displayed in main navigation of the rendered +manual. -.. _index-rst-project: - -Project -^^^^^^^ - -The *project* placeholder corresponds best to the project property of -Settings.cfg and - in case of a TYPO3 extension documentation - to the title -field of :file:`ext_emconf.php`. - - -.. _index-rst-extension-key: - -Extension key -^^^^^^^^^^^^^ - -The *extension-key* placeholder contains the TYPO3 extension key in case of a -TYPO3 extension documentation. - -Remove this field if the project has no extension key. - - -.. _index-rst-package-name: - -Package name -^^^^^^^^^^^^ - -The *package-name* placeholder contains the Composer package name of the -project. - -Remove this field if the project is no installable package. - - -.. _index-rst-author: - -Author -^^^^^^ - -The *author* placeholder best matches the copyright holders in the Settings.cfg -copyright property, since the authors of an open source project are also -copyright holders. It is also a good place to mention initiators and outstanding -contributors. - - -.. _index-rst-abstract: +.. _index-rst-table-of-contents: -Abstract -^^^^^^^^ +Configure the menu - the toctree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *abstract* placeholder contains a short and precise description of the -project. It should follow the abstract of :file:`README.rst` and - if -available - the description fields of :file:`ext_emconf.php` and -:file:`composer.json.` +The `toctree` on the start page can be hidden, it then only influences the main +navigation: +.. code-block:: rst -.. _index-rst-table-of-contents: + .. toctree:: + :hidden: -Table of contents -^^^^^^^^^^^^^^^^^ + Introduction/Index + Installation/Index + Configuration/Index + Usage/Index + Contribution/Index -The *table-of-contents* placeholder contains a rough table of contents (TOC), -which - in combination with the abstract - should give the reader a quick -overview. The TOC is built with the -:ref:`toctree directive ` as follows: +Or it can be inserted visibly into the start page to provide an entry point: .. code-block:: rst @@ -191,61 +124,52 @@ overview. The TOC is built with the Usage/Index Contribution/Index -The *maxdepth* property limits the depth of the page tree and *titlesonly* -specifies that only the titles of the pages are displayed, no other headings. -Both should emphasize the nature of an overview. - -The pages in the body of the directive are included in the TOC, and TOCs in -those pages are resolved recursively. The documentation author must edit the -list and provide a reST document at each of these file paths, interpreting the -file paths as relative to the current file. +For large pages it is advisable to limit the number of menu levels that will +be displayed on the startpage by setting :rest:`:maxdepth:`. This will not +limit the level of pages displayed in the main navigation. -In general, the file hierarchy should match the menu hierarchy, and a page must -be placed at either :file:`.rst` or :file:`/Index.rst` -- the latter if subpages exist or are expected. For example, the page of the -menu path "Usage > TYPO3 Backend > Shop Dashboard" should be stored at: +For more information on possible options on the `toctree` directive see +chapter :ref:`Toctrees in the reST reference `. -.. code-block:: none - - . - └── Documentation - └── Usage - └── Typo3Backend - └── ShopDashboard.rst +It is possible to use more then one `toctree` directive on the start page. +Each `toctree` should have a :rst:`:caption:` in this case. -or - if it has the subpage "Sell Widget" - at +The main navigation will then be divided into sections labeled by those +captions. The menu of the manual you are currently reading is an example for +that: -.. code-block:: none +.. code-block:: rst + :caption: Documentation/Index.rst - . - └── Documentation - └── Usage - └── Typo3Backend - └── ShopDashboard - ├── Index.rst - └── SellWidget.rst + .. toctree:: + :hidden: + :caption: Basics + About + HowToGetHelp + ... -.. _index-rst-meta-menu: + .. toctree:: + :hidden: + :caption: Howtos -Meta menu -^^^^^^^^^ + WritingContent/Index + WritingDocForExtension/Index + ... -The *meta-menu* placeholder builds a second menu that is not visible in the -content area of the page, but only in the left sidebar (desktop) or toggle menu -(mobile) - separate from the main menu. It contains links to functional pages, -such as the :ref:`Sitemap.rst ` and the -:ref:`genindex.rst `, which do not provide content specific to -this documentation, as follows: + .. toctree:: + :hidden: + :caption: Advanced -.. code-block:: rst + HowToAddTranslation/Index + GeneralConventions/HowToUpdateDocs + GeneralConventions/ReviewInformation .. toctree:: :hidden: + :caption: Maintainers - Sitemap - genindex - + Maintainers/Index .. index:: File structure; Documentation/Includes.rst.txt, Includes.rst.txt .. _includes-rst-txt: From 0b32867e6190bc6c40770e795b5c0c8d4534cab0 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:28:49 +0100 Subject: [PATCH 19/45] [TASK] Remove all inventories that are available by default (#374) --- Documentation/guides.xml | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/Documentation/guides.xml b/Documentation/guides.xml index e22b9e2b..65db5c6f 100644 --- a/Documentation/guides.xml +++ b/Documentation/guides.xml @@ -2,18 +2,7 @@ - - - - - - - - - - - From 700687c3f4ccc4ae32d271cf537a4dcc5bc5d080 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:31:54 +0100 Subject: [PATCH 20/45] [TASK] Remove section on Includes.rst.txt (#372) It is not needed anymore except in rare edge cases. --- .../Dashboard/IncludesRstTxt.rst.txt | 41 ---------------- .../Examples/IncludesRstTxt.rst.txt | 26 ---------- .../GettingStarted/IncludesRstTxt.rst.txt | 41 ---------------- .../FileStructure/IncludesRstTxt.rst.txt | 39 --------------- Documentation/CodeSnippets/codesnippets.php | 21 -------- .../GeneralConventions/FileStructure.rst | 49 ------------------- .../WritingReST/Reference/Code/InlineCode.rst | 13 +---- 7 files changed, 1 insertion(+), 229 deletions(-) delete mode 100644 Documentation/CodeSnippets/FileStructure/Dashboard/IncludesRstTxt.rst.txt delete mode 100644 Documentation/CodeSnippets/FileStructure/Examples/IncludesRstTxt.rst.txt delete mode 100644 Documentation/CodeSnippets/FileStructure/GettingStarted/IncludesRstTxt.rst.txt delete mode 100644 Documentation/CodeSnippets/FileStructure/IncludesRstTxt.rst.txt diff --git a/Documentation/CodeSnippets/FileStructure/Dashboard/IncludesRstTxt.rst.txt b/Documentation/CodeSnippets/FileStructure/Dashboard/IncludesRstTxt.rst.txt deleted file mode 100644 index 37721516..00000000 --- a/Documentation/CodeSnippets/FileStructure/Dashboard/IncludesRstTxt.rst.txt +++ /dev/null @@ -1,41 +0,0 @@ -.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets -.. Extracted from typo3/sysext/dashboard/Documentation/Includes.rst.txt - -.. code-block:: rst - :caption: Documentation/Includes.rst.txt of the Dashboard manual - - .. More information about this file: - https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - - .. ---------- - .. text roles - .. ---------- - - .. role:: aspect(emphasis) - .. role:: bash(code) - .. role:: html(code) - .. role:: js(code) - .. role:: php(code) - .. role:: rst(code) - .. role:: sep(strong) - .. role:: sql(code) - - .. role:: tsconfig(code) - :class: typoscript - - .. role:: typoscript(code) - .. role:: xml(code) - :class: html - - .. role:: yaml(code) - - .. default-role:: code - - .. --------- - .. highlight - .. --------- - - .. By default, code blocks use YAML syntax highlighting - - .. highlight:: yaml - \ No newline at end of file diff --git a/Documentation/CodeSnippets/FileStructure/Examples/IncludesRstTxt.rst.txt b/Documentation/CodeSnippets/FileStructure/Examples/IncludesRstTxt.rst.txt deleted file mode 100644 index 62fef64e..00000000 --- a/Documentation/CodeSnippets/FileStructure/Examples/IncludesRstTxt.rst.txt +++ /dev/null @@ -1,26 +0,0 @@ -.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets -.. Extracted from typo3conf/ext/examples/Documentation/Includes.rst.txt - -.. code-block:: rst - :caption: Documentation/Includes.rst.txt of the Examples extension manual - - .. This is 'Includes.txt'. It is included at the very top of each and - every ReST source file in THIS documentation project (= manual). - - .. role:: aspect(emphasis) - .. role:: html(code) - .. role:: js(code) - .. role:: php(code) - .. role:: pn(emphasis) - .. role:: sep(strong) - .. role:: sql(code) - .. role:: typoscript(code) - .. role:: xml(code) - .. role:: yaml(code) - - .. role:: ts(typoscript) - :class: typoscript - - .. default-role:: code - .. highlight:: php - \ No newline at end of file diff --git a/Documentation/CodeSnippets/FileStructure/GettingStarted/IncludesRstTxt.rst.txt b/Documentation/CodeSnippets/FileStructure/GettingStarted/IncludesRstTxt.rst.txt deleted file mode 100644 index 4c16e08d..00000000 --- a/Documentation/CodeSnippets/FileStructure/GettingStarted/IncludesRstTxt.rst.txt +++ /dev/null @@ -1,41 +0,0 @@ -.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets -.. Extracted from fileadmin/TYPO3CMS-Tutorial-GettingStarted/Documentation/Includes.rst.txt - -.. code-block:: rst - :caption: Documentation/Includes.rst.txt of the Getting Started tutorial - - .. More information about this file: - https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - - .. ---------- - .. text roles - .. ---------- - - .. role:: aspect(emphasis) - .. role:: bash(code) - .. role:: html(code) - .. role:: js(code) - .. role:: php(code) - .. role:: rst(code) - .. role:: sep(strong) - .. role:: sql(code) - - .. role:: tsconfig(code) - :class: typoscript - - .. role:: typoscript(code) - .. role:: xml(code) - :class: html - - .. role:: yaml(code) - - .. default-role:: code - - .. --------- - .. highlight - .. --------- - - .. By default, code blocks use PHP syntax highlighting - - .. highlight:: php - \ No newline at end of file diff --git a/Documentation/CodeSnippets/FileStructure/IncludesRstTxt.rst.txt b/Documentation/CodeSnippets/FileStructure/IncludesRstTxt.rst.txt deleted file mode 100644 index 33232f24..00000000 --- a/Documentation/CodeSnippets/FileStructure/IncludesRstTxt.rst.txt +++ /dev/null @@ -1,39 +0,0 @@ - -.. code-block:: rst - :caption: Documentation/Includes.rst.txt - - .. More information about this file: - .. https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - - .. ---------- - .. text roles - .. ---------- - - .. role:: aspect(emphasis) - .. role:: bash(code) - .. role:: css(code) - .. role:: html(code) - .. role:: js(code) - .. role:: php(code) - .. role:: rst(code) - .. role:: sep(strong) - .. role:: sql(code) - - .. role:: tsconfig(code) - :class: typoscript - - .. role:: typoscript(code) - .. role:: xml(code) - :class: html - - .. role:: yaml(code) - - .. default-role:: code - - .. --------- - .. highlight - .. --------- - - .. By default, code blocks use PHP syntax highlighting - - .. highlight:: php diff --git a/Documentation/CodeSnippets/codesnippets.php b/Documentation/CodeSnippets/codesnippets.php index 997ec307..595ebb31 100644 --- a/Documentation/CodeSnippets/codesnippets.php +++ b/Documentation/CodeSnippets/codesnippets.php @@ -46,27 +46,6 @@ 'targetFileName' => 'FileStructure/Examples/ReadmeRst.rst.txt', 'language' => 'rst', ], - [ - 'action'=> 'createCodeSnippet', - 'caption' => 'Documentation/Includes.rst.txt of the Getting Started tutorial', - 'sourceFile'=> 'fileadmin/TYPO3CMS-Tutorial-GettingStarted/Documentation/Includes.rst.txt', - 'targetFileName' => 'FileStructure/GettingStarted/IncludesRstTxt.rst.txt', - 'language' => 'rst', - ], - [ - 'action'=> 'createCodeSnippet', - 'caption' => 'Documentation/Includes.rst.txt of the Dashboard manual', - 'sourceFile'=> 'typo3/sysext/dashboard/Documentation/Includes.rst.txt', - 'targetFileName' => 'FileStructure/Dashboard/IncludesRstTxt.rst.txt', - 'language' => 'rst', - ], - [ - 'action'=> 'createCodeSnippet', - 'caption' => 'Documentation/Includes.rst.txt of the Examples extension manual', - 'sourceFile'=> 'typo3conf/ext/examples/Documentation/Includes.rst.txt', - 'targetFileName' => 'FileStructure/Examples/IncludesRstTxt.rst.txt', - 'language' => 'rst', - ], [ 'action'=> 'createCodeSnippet', 'caption' => 'Documentation/Settings.cfg of the Getting Started tutorial', diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 8a3f85c0..a89cc58f 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -171,55 +171,6 @@ that: Maintainers/Index -.. index:: File structure; Documentation/Includes.rst.txt, Includes.rst.txt -.. _includes-rst-txt: - -Global rst settings: :file:`Documentation/Includes.rst.txt` ------------------------------------------------------------ - -Default style configurations are bundled in a central -Documentation/Includes.rst.txt file and included at the beginning of -each reST file. An absolute file path should be passed to use the same include -statement on every page, regardless of which folder level the reST file is in: - -.. code-block:: rst - - .. include:: /Includes.rst.txt - -Normally, the include directive is used with files with the extension *.txt*. -To help your IDE associate reST syntax highlighting with the included files, -we use the specific *.rst.txt* file extension. - -Typical style configurations in TYPO3 documentation are definitions of custom -text roles that allow :ref:`inline code ` to be written. This is a -typical Includes.rst.txt that provides text roles for most programming and -markup languages used in a TYPO3 project: - -.. tabs:: - - .. group-tab:: With placeholders - - .. include:: /CodeSnippets/FileStructure/IncludesRstTxt.rst.txt - - .. group-tab:: Third party extension - - .. include:: /CodeSnippets/FileStructure/Examples/IncludesRstTxt.rst.txt - - .. group-tab:: System extension - - .. include:: /CodeSnippets/FileStructure/Dashboard/IncludesRstTxt.rst.txt - - .. group-tab:: Official manual - - .. include:: /CodeSnippets/FileStructure/GettingStarted/IncludesRstTxt.rst.txt - -The text roles that have been assigned a specific class mimic the syntax -highlighting of another language. This is done to avoid confusing the reader -with too many different colors. For example, XML inline code may be semantically -marked with `:xml:`, but under the hood it uses the same highlighting as -`:html:`. - - .. index:: File structure; Documentation/Sitemap.rst, Sitemap.rst .. _sitemap-rst: diff --git a/Documentation/WritingReST/Reference/Code/InlineCode.rst b/Documentation/WritingReST/Reference/Code/InlineCode.rst index 1d046c52..bd39e5ca 100644 --- a/Documentation/WritingReST/Reference/Code/InlineCode.rst +++ b/Documentation/WritingReST/Reference/Code/InlineCode.rst @@ -158,9 +158,7 @@ within sentences is *inline code*. * is styled somewhat differently, * has **no** syntax highlighting, * does **not** need to be syntactically correct, -* can be compared to `...` tags in html, -* and is made up by self-defined names. For example, look at the :file:`/Includes.rst.txt` - file to see how `:php:` is defined. +* can be compared to `...` tags in html In contrast, *code-blocks* @@ -179,15 +177,6 @@ For all officials TYPO3 manuals `php` is set as default highlight language with the exception of the TypoScript manuals, where `typoscript` is the default. - -About the 'Includes.rst.txt' file ---------------------------------- - -In general, the manual you are working on will already contain an -:ref:`Includes.rst.txt ` file. In that file, the text roles -are defined. - - You need a custom text role? ---------------------------- From 85e465584931b6b1abc78c3531396ae24160c6c3 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:52:25 +0100 Subject: [PATCH 21/45] [TASK] Remove genindex (#375) * [TASK] Remove section on genindex We currently do not support a generated output of this file and in most cases it was not very usefull. * [TASK] Remove genindex It was not really usefull and does not work in the new rendering. We will use the indexes to enhance the elastic search instead --- .../GeneralConventions/FileStructure.rst | 27 +------------------ Documentation/Index.rst | 1 - Documentation/genindex.rst | 7 ----- 3 files changed, 1 insertion(+), 34 deletions(-) delete mode 100644 Documentation/genindex.rst diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index a89cc58f..e9e47e64 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -178,7 +178,7 @@ Optional: :file:`Documentation/Sitemap.rst` ------------------------------------------- The :file:`Sitemap.rst` contains the sitemap of the documentation. -It is an almost empty file that is automatically filled by the Sphinx template. +It is an almost empty file that is automatically filled during rendering. .. code-block:: rst @@ -193,31 +193,6 @@ It is an almost empty file that is automatically filled by the Sphinx template. .. The sitemap.html template will insert here the page tree automatically. -.. index:: File structure; Documentation/genindex.rst, genindex.rst -.. _genindex-rst: - -Optional: Automatic index: :file:`Documentation/genindex.rst` -------------------------------------------------------------- - -The genindex.rst shows a list of all indexes of the documentation pages. It is -an almost empty file that is automatically filled by Sphinx. An index can be -manually applied to each documentation location using the -:rst:dir:`index directive `. -In addition, some content elements automatically generate indexes, such as the -:ref:`configuration values ` and -:ref:`PHP domain ` elements. - -.. code-block:: rst - - .. include:: /Includes.rst.txt - - ===== - Index - ===== - - .. Sphinx will insert here the general index automatically. - - .. index:: File structure; Documentation/Settings.cfg, Settings.cfg .. _settings-cfg: diff --git a/Documentation/Index.rst b/Documentation/Index.rst index a8e37f8e..aec88d48 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -137,4 +137,3 @@ What's new in this guide? :hidden: Sitemap - genindex diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst deleted file mode 100644 index 806ec56a..00000000 --- a/Documentation/genindex.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. include:: /Includes.rst.txt - -===== -Index -===== - -.. Sphinx will insert here the general index automatically. From 22aac513f536b96f557e94f3bd62200501488433 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:54:18 +0100 Subject: [PATCH 22/45] [TASK] Move default language to guides.xml (#373) The textroles are already defined in the render-guides. the Includes.rst.txt is only needed now to display central messages. I will include a central message about the scope of this manual (render-guides only) in a follow-up. --- Documentation/Includes.rst.txt | 36 +--------------------------------- Documentation/guides.xml | 7 ++++++- 2 files changed, 7 insertions(+), 36 deletions(-) diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt index b981f2fb..23625074 100644 --- a/Documentation/Includes.rst.txt +++ b/Documentation/Includes.rst.txt @@ -1,35 +1 @@ -.. More information about this file: - https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - -.. ---------- -.. text roles -.. ---------- - -.. role:: aspect(emphasis) -.. role:: bash(code) -.. role:: css(code) -.. role:: html(code) -.. role:: js(code) -.. role:: php(code) -.. role:: rst(code) -.. role:: sep(strong) -.. role:: sql(code) - -.. role:: tsconfig(code) - :class: typoscript - -.. role:: typoscript(code) -.. role:: xml(code) - :class: html - -.. role:: yaml(code) - -.. default-role:: code - -.. --------- -.. highlight -.. --------- - -.. By default, code blocks use PHP syntax highlighting - -.. highlight:: php +.. You can put central messages to display on all pages here diff --git a/Documentation/guides.xml b/Documentation/guides.xml index 65db5c6f..bf797eb5 100644 --- a/Documentation/guides.xml +++ b/Documentation/guides.xml @@ -1,5 +1,10 @@ - + From 55b8b5a23b1b84d8c11a90fc163ac6331070937c Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sat, 27 Jan 2024 18:17:04 +0100 Subject: [PATCH 23/45] [FEATURE] Document guides.xml (#376) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I will explain the interlink mapping in depth in a follow-up. Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../GeneralConventions/FileStructure.rst | 203 +---------------- .../GeneralConventions/GuidesXml.rst | 205 ++++++++++++++++++ .../GeneralConventions/_guides-simple.xml | 20 ++ .../WritingDocForExtension/Migrate.rst | 2 + 4 files changed, 239 insertions(+), 191 deletions(-) create mode 100644 Documentation/GeneralConventions/GuidesXml.rst create mode 100644 Documentation/GeneralConventions/_guides-simple.xml diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index e9e47e64..121c2ebb 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -195,204 +195,25 @@ It is an almost empty file that is automatically filled during rendering. .. index:: File structure; Documentation/Settings.cfg, Settings.cfg .. _settings-cfg: +.. _settings-guides-xml: -Settings: :file:`Documentation/Settings.cfg` +Settings: :file:`Documentation/guides.xml` -------------------------------------------- -This file contains the configuration for the Sphinx theme. The configuration -values are used to fill placeholders in the theme. It consists of sections -starting with a keyword in brackets, e.g. ``[general]``: Make sure that all -properties are in the correct section! +This file contains the metadata and configuration for the rendering with the +TYPO3 theme. -.. tabs:: - - .. group-tab:: With placeholders - - .. include:: /CodeSnippets/FileStructure/SettingsCfg.rst.txt - - The placeholders of pattern `` must be replaced manually by the author of - the documentation, and commented or set empty if not required. - - .. group-tab:: Third party extension - - .. include:: /CodeSnippets/FileStructure/Examples/SettingsCfg.rst.txt - - .. group-tab:: System extension - - .. include:: /CodeSnippets/FileStructure/Dashboard/SettingsCfg.rst.txt - - .. group-tab:: Official manual - - .. include:: /CodeSnippets/FileStructure/GettingStarted/SettingsCfg.rst.txt - -.. _settings-cfg-project: - -Project -^^^^^^^ - -The *project* property contains the title of the project and is displayed in the -left sidebar (desktop) or the top (mobile) of the theme and in the title meta -tag. - -Common values are in the official TYPO3 manuals - -#. ` Guide`, e.g. "Frontend Localization Guide", - for collections of articles on a specific topic -#. ` Reference`, e.g. "TSconfig Reference", - for a complete encyclopedia -#. ` Tutorial`, e.g. "Editors Tutorial", - for collections of tutorials on a specific topic - -and in TYPO3 extension documentations - -* ``, e.g. "Import / Export" or "Mask". - - -.. _settings-cfg-version-and-release: - -Version and release -^^^^^^^^^^^^^^^^^^^ - -The properties *version* and *release* both contain the version of the manual -and mostly correspond to the version of the TYPO3 LTS or TYPO3 extension to -which the documentation refers. - -The version is shown below the title in the theme's release switch and in the -title meta tag, the release is not shown currently - but it should be -kept anyway to satisfy internal requirements. - -Normally both properties are set to the same value, either - -* `.`, e.g. "11.5", or -* `..`, e.g. "11.5.1", or -* `main (development)`. - -For the release switch entries, only the major and minor versions are -considered. - - -.. _settings-cfg-copyright: - -Copyright -^^^^^^^^^ - -The *copyright* property contains the copyright claim of the project. It is -displayed in the footer as "© Copyright " and has in most use cases -of the TYPO3 world the values: - -#. `since by the TYPO3 contributors`, - for example "since 1999 by the TYPO3 contributors" (official TYPO3 manuals and TYPO3 - system extensions) -#. `since by & contributors`, - for example "since 1999 by dkd & contributors" (third-party TYPO3 extensions) - - -.. _settings-cfg-github-workflow: - -GitHub workflow -^^^^^^^^^^^^^^^ - -The *github_repository* and *github_branch* properties must be set to provide -the "Edit on GitHub" button, which allows the reader to jump from the currently -viewed documentation directly to the associated GitHub repository and edit the -page file. - -If the project is hosted on GitHub and public contributions are desired, these -properties should be set accordingly: - -1. `/`, for example to "TYPO3-Documentation/TYPO3CMS-Reference-TCA" - or "FriendsOfTYPO3/extension_builder". -2. ``, for example on "main" or "10.x". - - -.. _settings-cfg-footer-links: - -Footer links -^^^^^^^^^^^^ - -The *project_* properties provide all links with the name "" in -the footer of the documentation that guide the user to other aspects of the -project than the documentation, for example to the project page in the TER: - -* *project_home* is set to the homepage URL of the project. For official TYPO3 - manuals this is the public base URL at docs.typo3.org, for public TYPO3 - extensions this is the associated TER page or a custom project website, for - example - - * "\https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" or - * "\https://extensions.typo3.org/extension/news". - -* *project_contact* is usually set to an email address or Slack channel URL of - the team behind the project, for example - - * "\mailto:documentation\@typo3.org" or - * "\https://typo3.slack.com/archives/C028JEPJL". - -* *project_repository* is set to the repository of the project's VCS, for - example - - * "\https://github.com/FriendsOfTYPO3/extension_builder". - -* *project_issues* is set to the location where project issues are to be - created and edited, for example - - * "\https://github.com/FriendsOfTYPO3/extension_builder/issues". - -* *project_discussions* is used in the rare case that project-related - discussions take place in locations other than those defined by the - project_contact and project_issues properties, for example - - * "\https://github.com/FriendsOfTYPO3/extension_builder/discussions". - - -.. _settings-cfg-use-opensearch: - -Use OpenSearch -^^^^^^^^^^^^^^ - -If the *use_opensearch* property is set to the public URL of the documentation, -Sphinx renders an OpenSearch description file of the documentation, which allows -most browsers to treat the internal search of your documentation as a global -search engine and include it in their search bar like any other search engine. -This seems useful if your documentation is a large reference that is of high -public interest and likely to be searched frequently by readers. Good examples -of this are the PHP or TYPO3 Core references, for example -"\https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/", while the -TYPO3 extension documentations probably are not. - - -.. _settings-cfg-intersphinx-mapping: - -Intersphinx mapping -^^^^^^^^^^^^^^^^^^^ - -The *[intersphinx_mapping]* section contains base URLs of public manuals for -convenient and verified cross-referencing. - -For example, if you uncomment the *t3start* mapping in the Settings.cfg above, -the :samp:`https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/Extensions/Management.html` -page can be referenced with - -.. code-block:: rst - - :doc:`t3start:Extensions/Management` - -and the fragment :samp:`#install-extension-with-composer` on the same page with - -.. code-block:: rst +Read more about the :ref:`guides-xml`. - :ref:`t3start:install-extension-with-composer` +.. 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 `. -The prerequisite is that the target manual is also compiled with Sphinx and -provides an objects.inv file in the root of the documentation that -contains all reference targets. Since this file is binary, the rendering -toolchain provides a twin :file:`objects.inv.json` file that allows the reader -to easily look up reference targets. An example of this is this -`production objects.inv.json `__. +Example: -If a target reference becomes unavailable during documentation rendering, for -example if it has been permanently removed, a warning is issued and stored in -the toolchain log file at :file:`Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt`. +.. literalinclude:: _guides-simple.xml + :capition: Documentation/guides.xml .. index:: Single file documentation diff --git a/Documentation/GeneralConventions/GuidesXml.rst b/Documentation/GeneralConventions/GuidesXml.rst new file mode 100644 index 00000000..e6c0fe17 --- /dev/null +++ b/Documentation/GeneralConventions/GuidesXml.rst @@ -0,0 +1,205 @@ +.. _guides-xml: + +================================ +:file:`Documentation/guides.xml` +================================ + +This XML file contains meta information and configuration used during rendering +of a manual. + +Example: + +.. literalinclude:: _guides-simple.xml + :caption: Documentation/guides.xml + +.. 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 + +.. _settings-guides: + +The `` tag +================== + +It is used for general configuration during parsing and rendering. + +.. _settings-guides-project: + +The `` tag +=================== + +This tag can contain the following meta information: + +Project title +------------- + +The *project* tag contains the title of the project and is displayed in the +left sidebar (desktop) or the top (mobile) of the theme and in the title meta +tag. + +For TYPO3 extensions we suggest to use the extension name in a readable +format: + +* Import / Export tool +* News +* Mask + +Common values are in the official TYPO3 manuals + +#. ` Guide`, e.g. "Frontend Localization Guide", + for collections of articles on a specific topic +#. ` Reference`, e.g. "TSconfig Reference", + for a complete reference +#. ` Tutorial`, e.g. "Editors Tutorial", + for collections of tutorials on a specific topic + +.. _settings-guides-version-and-release: + +Version and release +------------------- + +The attributes *version* and *release* both contain the version of the manual +and mostly correspond to the version of the TYPO3 LTS or TYPO3 extension to +which the documentation refers. + +The version is shown below the title in the theme's release switch and in the +title meta tag, the release is not shown currently - but it should be +kept anyway to satisfy internal requirements. + +version + The major project version, used as the replacement for :rst:`|version|`. + For example this may be something like 12.4. + +release + The full project version, used as the replacement for :rst:`|release|` + For example 13.0.0-dev. + +If you do not need the separation provided between version and release, +just set them both to the same value. + +.. _settings-guides-copyright: + +Copyright +--------- + +The *copyright* attribute contains the copyright claim of the project. It is +displayed in the footer as "© Copyright " and has in most use cases +in the TYPO3 world the values: + +#. `since by the TYPO3 contributors`, + for example "since 1999 by the TYPO3 contributors" (official TYPO3 manuals and TYPO3 + system extensions) +#. `since by & contributors`, + for example "since 1999 by John Doe & contributors" (third-party TYPO3 extensions) + +.. _settings-guides-theme: + +TYPO3 Theme settings +==================== + +Further settings can be made in the XML tag +:xml:``. +The class attribute is mandatory, it references the extension that is used +to render the documentation with the TYPO3 documentation theme. + +.. _settings-guides-github-workflow: + +Configure the "Edit on GitHub" button +------------------------------------- + +The *github_repository* and *github_branch* attributes should be set to provide +the "Edit on GitHub" button, which allows the reader to jump from the currently +viewed documentation directly to the associated GitHub repository and edit the +page file. + +If the project is hosted on GitHub and public contributions are welcome, these +attributes should be set accordingly: + +1. `/`, for example to "TYPO3-Documentation/TYPO3CMS-Reference-TCA" + or "FriendsOfTYPO3/extension_builder". +2. ``, for example on "main" or "10.x". + +For example: + +.. code-block:: xml + :caption: Documentation/guides.xml, excerpt + + + + +.. _settings-guides-footer-links: + +Footer links +------------ + +The *project_* attributes provide all links with the name "" in +the footer of the documentation that guide the user to other aspects of the +project than the documentation, for example to the project page in the +TYPO3 Extension Repository (TER): + +project_home + is set to the homepage URL of the project. For official TYPO3 + manuals this is the public base URL at docs.typo3.org, for public TYPO3 + extensions this is the associated TER page or a custom project website, for + example + + * `https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/` or + * `https://extensions.typo3.org/extension/news`. + +project_contact + is usually set to an email address or Slack channel URL of + the team behind the project, for example + + * `mailto:documentation\@typo3.org` or + * `https://typo3.slack.com/archives/C028JEPJL`. + +project_repository + is set to the repository of the project's VCS, for + example + + * `https://github.com/FriendsOfTYPO3/extension_builder`. + +project_issues + is set to the location where project issues are to be + created and edited, for example + + * `https://github.com/FriendsOfTYPO3/extension_builder/issues` + +project_discussions + is used in the rare case that project-related + discussions take place in locations other than those defined by the + project_contact and project_issues attributes, for example + + * `https://github.com/FriendsOfTYPO3/extension_builder/discussions`. + +For example: + +.. code-block:: xml + :caption: Documentation/guides.xml, excerpt + + + +.. _settings-guides-interlink-mapping: + +Interlink mapping +================= + +.. todo: describe interlink mapping more detailed + +It is possible, though rarely needed to define custom interlink mappings: + +For example: + +.. code-block:: xml + :caption: Documentation/guides.xml, excerpt + + diff --git a/Documentation/GeneralConventions/_guides-simple.xml b/Documentation/GeneralConventions/_guides-simple.xml new file mode 100644 index 00000000..80574345 --- /dev/null +++ b/Documentation/GeneralConventions/_guides-simple.xml @@ -0,0 +1,20 @@ + + + + + + diff --git a/Documentation/WritingDocForExtension/Migrate.rst b/Documentation/WritingDocForExtension/Migrate.rst index 2f0e7f33..5198190b 100644 --- a/Documentation/WritingDocForExtension/Migrate.rst +++ b/Documentation/WritingDocForExtension/Migrate.rst @@ -22,6 +22,8 @@ used. In the transition period we detect if a file called :file:`Documentation/guides.xml` is present and then switch to the new PHP-based rendering. +.. _migrate_guides_xml: + Create the settings file :file:`Documentation/guides.xml` ========================================================= From a0e581ea652d19edc3dcf185df62ab5df6ed6e90 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:19:31 +0100 Subject: [PATCH 24/45] [FEATURE] Document the preferred Core Version (#378) --- .../GeneralConventions/GuidesXml.rst | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Documentation/GeneralConventions/GuidesXml.rst b/Documentation/GeneralConventions/GuidesXml.rst index e6c0fe17..dd95ce30 100644 --- a/Documentation/GeneralConventions/GuidesXml.rst +++ b/Documentation/GeneralConventions/GuidesXml.rst @@ -103,6 +103,27 @@ Further settings can be made in the XML tag The class attribute is mandatory, it references the extension that is used to render the documentation with the TYPO3 documentation theme. +.. _preferred_typo3_version: + +Preferred TYPO3 Core version +---------------------------- + +You can set the preferred TYPO3 Core version. This version is used to determine +the desired version for links to other manuals and system extensions. + +.. code-block:: xml + :caption: Documentation/guides.xml + + + +If no preferred version is set it defaults to `stable`. Possible values are: + +`main`, `stable` (latest LTS), `oldstable` (old LTS) or an explicit LTS / eLTS +version like `12.4` or `8.7`. + +.. todo: Link to interlink chapter once it is written + .. _settings-guides-github-workflow: Configure the "Edit on GitHub" button From dbd400448356ebd9f50051822b6f6978b9952206 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:27:13 +0100 Subject: [PATCH 25/45] [TASK] guides.xml chapter improvements (#379) * Include in the toctree * Include a table of contents * Improve the title --- .../GeneralConventions/GuidesXml.rst | 10 +++++-- Documentation/GeneralConventions/Index.rst | 29 +++++++++---------- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/Documentation/GeneralConventions/GuidesXml.rst b/Documentation/GeneralConventions/GuidesXml.rst index dd95ce30..91ca7ab5 100644 --- a/Documentation/GeneralConventions/GuidesXml.rst +++ b/Documentation/GeneralConventions/GuidesXml.rst @@ -1,12 +1,16 @@ .. _guides-xml: -================================ -:file:`Documentation/guides.xml` -================================ +=========================================== +Configuration of the rendering - guides.xml +=========================================== This XML file contains meta information and configuration used during rendering of a manual. +.. contents:: Table of Contents: + :depth: 2 + :local: + Example: .. literalinclude:: _guides-simple.xml diff --git a/Documentation/GeneralConventions/Index.rst b/Documentation/GeneralConventions/Index.rst index 7e5df812..2afa3879 100644 --- a/Documentation/GeneralConventions/Index.rst +++ b/Documentation/GeneralConventions/Index.rst @@ -92,19 +92,16 @@ be found in the subchapters. This will look like this: :guilabel:`Admin Tools > Extensions` - - - -**Table of contents** - -.. toctree:: - :maxdepth: 1 - - ContentStyleGuide - Glossary - FileStructure - Format - CodingGuidelines - GuidelinesForImages - CommitMessages - Licenses +.. toctree:: + :caption: Table of contents + :maxdepth: 1 + + ContentStyleGuide + Glossary + FileStructure + GuidesXml + Format + CodingGuidelines + GuidelinesForImages + CommitMessages + Licenses From 7b8f9c5d805b1167239580b1b5f782eea22d542e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 29 Jan 2024 21:46:02 +0100 Subject: [PATCH 26/45] [TASK] Remove "Writing Content" section (#383) We do not really have knowledge in this area and the information is quite outdated Co-authored-by: lina.wolf --- Documentation/Index.rst | 1 - Documentation/WritingContent/Index.rst | 31 ---- Documentation/WritingContent/Resources.rst | 48 ----- Documentation/WritingContent/Tutorial.rst | 62 ------- .../WritingContent/WritingContentTips.rst | 171 ------------------ 5 files changed, 313 deletions(-) delete mode 100644 Documentation/WritingContent/Index.rst delete mode 100644 Documentation/WritingContent/Resources.rst delete mode 100644 Documentation/WritingContent/Tutorial.rst delete mode 100644 Documentation/WritingContent/WritingContentTips.rst diff --git a/Documentation/Index.rst b/Documentation/Index.rst index aec88d48..060e740b 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -113,7 +113,6 @@ What's new in this guide? :hidden: :caption: HOWTOS - WritingContent/Index WritingDocForExtension/Index WritingDocsOfficial/Index RenderingDocs/Index diff --git a/Documentation/WritingContent/Index.rst b/Documentation/WritingContent/Index.rst deleted file mode 100644 index 1ac55744..00000000 --- a/Documentation/WritingContent/Index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. _writing-content: - -========================= -How to write good content -========================= - - -* Divio: `"The documentation system" `__, based on - Daniele Procida's 2017 blog post, "What nobody tells you about documentation". - It establishes four distinct categories of documentation content. - -.. figure:: /Images/content-types.png - :class: with-shadow - - Overview of content types, taken from Daniele Procida - -**Table of contents** - -.. toctree:: - :titlesonly: - - WritingContentTips - Tutorial - Resources - - -.. todo:: finalize Guide.rst - - diff --git a/Documentation/WritingContent/Resources.rst b/Documentation/WritingContent/Resources.rst deleted file mode 100644 index 8c2c10d5..00000000 --- a/Documentation/WritingContent/Resources.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: Writing; Resources -.. _resources: - -================= -Writing Resources -================= - -Online Resources -================ - -documentation writing: - -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. - -general writing tips: - -* `"8 Tips for Better Readability" by Roby Collinge - `__ - is a very good resource. However, some of the tips do not concern you as - a writer. They are only relevant for theme development. As a writer, skip - right down to tip 5. -* `Neil Patel: How to Write With Clarity: 9 Tips for Simplifying Your Message `__ - This is also not an article that is specific to documentation, but the tips - are very good and general, especially for writing in clarity in mind. - - -.. pull-quote:: - - Clarity means making your content easy to understand. - - -- Neil Patel - - -* `Strunk & White: "The Elements of Style `__ - is a classic. Many principles still apply. - -Videos -====== - -* `Daniele Procida: What nobody tells you about documentation `__ - - -Programs -======== - -* Google Season of Docs diff --git a/Documentation/WritingContent/Tutorial.rst b/Documentation/WritingContent/Tutorial.rst deleted file mode 100644 index 6f9acf30..00000000 --- a/Documentation/WritingContent/Tutorial.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: pair: Writing; Tutorials -.. todo:: Add information about writing a tutorial - -.. _writing-tutorial: - -================== -Writing a tutorial -================== - - -Text used so far in the first section of TYPO3 tutorials: - -*"This document is a tutorial. Tutorials are designed to be step-by-step instructions -specifically created to walk a beginner through a particular task from beginning to -end. To facilitate effective learning, tutorials provide examples to illustrate -the subjects they cover. In addition, tutorials provide guidance on how to avoid -common pitfalls and highlight key concepts that should be remembered for future reference."* - -From looking at the literature mentioned below we should consider the following key points: - -* a tutorial is a lesson, learning oriented, showing steps to complete something, making the reader more knowledgable - -* the reader should achieve something meaningful and experience success, find it doable and enjoyable, enhance competence, gain confidence, and wants to do it again. - -* concentrate on practical knowledge, not theoretical knowledge. Learn a new craft or skill, concentrate on learning by by doing - -Guidelines: - -* allow the user to learn by doing, - -* go from simple to complex - -* Get the user started - -* it’s ok to show the steps the beginner understands best. “best practice” may be something different. How an experienced user would do it may be something different. - -* The goal is to get the reader started, not to get them to a final destination. - -* Make sure that your tutorial works! - -* inspire the beginner’s confidence: in the software, in the tutorial, in the tutor and, of course, in their own ability to achieve what’s being asked of them. - -* Ensure the user sees results immediately - -* The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment. - -* Your tutorial must be reliably repeatable. - -* Focus on concrete steps, not abstract concepts. The temptation to introduce abstraction is huge: resist! - -* Provide the minimum necessary explanation - -* Focus only on the steps the user needs to take - -Literature -========== - -* `Ubuntu: How to write a tutorial `__ -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. diff --git a/Documentation/WritingContent/WritingContentTips.rst b/Documentation/WritingContent/WritingContentTips.rst deleted file mode 100644 index 837c2cdb..00000000 --- a/Documentation/WritingContent/WritingContentTips.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: Writing; Content -.. _write-good-content: - -============================= -Tips for writing good content -============================= - - -.. index:: Writing; Readability - -How people read on the web -========================== - -People read differently on the web than they read print media. - -.. pull-quote:: - - "On the web, however, most of us scan information, jumping - from one point of interest to the next, hoping to trip over - some relevant facts. In fact, according to a study by the Norman - Nielsen Group, your visitors will only ready between 20 and 28% - of the words on your site." - - -- `"8 Tips for Better Readability" by Roby Collinge `__ - -This information is not specific to online documentation, it is about -information on the web in general. Nonetheless, we should consider -that information about reading on the Web at least partly -applies to reading online documentation as well. - -So: - -* Readers on the web often do not read, they scan (skim). -* Additionally, they often do not read entire manuals, they google for - the information they are looking for and start reading there. - - -.. index:: Writing; Online - -Tip 1: Write for online reading -=============================== - -* Make it easier for the reader who has not read previous pages. -* Make sure, the title is clear. -* Text with good formatting is easier to scan (see the next two - tips) - - -Tip 2: Use paragraphs -===================== - -In any case, avoid long "walls of text". Give the eye something to cling to. - -Tip 3: Use subheaders -===================== - -Look at `this page `__ - -Imagine removing all the subheaders and then reading it. - - -Tip 4: Think about your audience -================================ - -What is the typical target audience of your text? -Put yourself in the shoes of your readers while writing. -Find someone from your target audience to read your text and -give feedback. - - -Tip 5: Use a consistent and clear vocabulary -============================================ - -Use specific (not ambiguous) language. - - -Tip 6: Write simple, short sentences -==================================== - -Keep the text as short as possible. Edit out anything that can be omitted -without loss: - -.. pull-quote:: - - "Vigorous writing is concise. A sentence should contain no unnecessary words, a - paragraph no unnecessary sentences, for the same reason that a drawing should have no - unnecessary lines and a machine no unnecessary parts." - - -- `Strunk & White: "The Elements of Style `__ - - -Tip 7: Use a spellchecker -========================== - -.. hint:: - - Use a spellchecker that also points out grammar mistakes and gives - recommendations for style improvements. Try out this - `free online check `__ by - Grammarly. - - -Tip 8: Use Stack Overflow to learn -================================== - -Yes, `Stack Overflow `__ can be a good teacher. Or, we -should add, its users are. - -You may notice, there are some good -answers on StackOverflow, ideally formatted for readability, very well written -and structured. If you have not signed up for StackOverflow yet, do it now -and start writing questions and / or answers. - -Advanced Stack Overflow users `often use number or -unnumbered lists `__ and other formatting -elements. - -Of course, it is better to keep the text on Stack Overflow as short as possible, -but if the text is longer than a paragraph, lists help to structure the text -and make it more readable. - -Additionally, some users are very good at explaining things. - -See how this `highly voted answer by Mysticial on branch prediction -`__ uses a railroad junction -analogy. - -You can use the advanced search to search for `highly voted answers -`__, -but note that number of votes correlates with a number of factors. Quality is not always -the decisive factor (it also depends on whether the information is relevant for -a high number of users). - - -Tip 9: Read other documentation -=============================== - -* Ask yourself questions: What works for you, what doesn't? - -Here are some tips: - -* `Docker `__ -* Google Developer: `Get Started With Analyzing Runtime Performance `__ -* `use TYPO3 blog `__ - - -Tip 10: Read your own content -============================= - -When you write new content, finish it, **wait a few days**, and then read it again! - - -.. _write-good-content-resources: - -Additional Resources -==================== - -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. -* `How to fix the 7 most common glitches in technical writing `_ -* `"8 Tips for Better Readability" by Roby Collinge - `__ - is a very good resource. However, some of the tips do not concern you as - a writer. They are only relevant for theme development. As a writer, skip - right down to tip 5. -* `Strunk & White: "The Elements of Style `__ - is a classic. Many principles still apply. - -You can find more in the :ref:`resources` section. From 7491d7b321b584d695e6c4aa3db82f7c8fd858e5 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 29 Jan 2024 22:05:42 +0100 Subject: [PATCH 27/45] [TASK] Fix rendering warnings --- Documentation/BasicPrinciples.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/BasicPrinciples.rst b/Documentation/BasicPrinciples.rst index 44b30002..e59b3fe3 100644 --- a/Documentation/BasicPrinciples.rst +++ b/Documentation/BasicPrinciples.rst @@ -119,8 +119,6 @@ learning, tutorials provide examples to illustrate the subjects they cover. They may not necessarily follow best-practices by the letter. They are designed to make it easier to get started. -:ref:`Read more ... ` - The definitions for tutorials, guides, explanations and references were taken from `Daniele Procida: What nobody tells you about documentation `__ From 88e247c2a306fcaaa6bd481daf68683bc706330b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 08:13:19 +0100 Subject: [PATCH 28/45] [TASK] Remove graphviz support (#385) It was never really adopted and will not work anymore in the new rendering. The uml graphs can be used instead Co-authored-by: lina.wolf --- Documentation/WritingReST/CheatSheet.rst | 65 --- .../WritingReST/Reference/Graphics/Graphs.rst | 484 ------------------ 2 files changed, 549 deletions(-) delete mode 100644 Documentation/WritingReST/Reference/Graphics/Graphs.rst diff --git a/Documentation/WritingReST/CheatSheet.rst b/Documentation/WritingReST/CheatSheet.rst index ca5d3dc2..1c953830 100644 --- a/Documentation/WritingReST/CheatSheet.rst +++ b/Documentation/WritingReST/CheatSheet.rst @@ -710,71 +710,6 @@ Source: echo $null >> public/FIRST_INSTALL - -:ref:`Graphs ` -=============================== - -**How it looks:** - -.. graphviz:: - - graph { - user [ - shape=plaintext; - width=4; - label="User"; - style=""; - ] - view [ - shape=box; - width=4; - label=<View
Displaying the data>; - ] - controller [ - shape=box; - width=4; - label=<Controller
Control of functionality>; - ] - model [ - shape=box; - width=4; - label=<Model
Domain model and domain logic>; - ] - user -- view -- controller -- model; - } - -Source: - -.. code-block:: rst - - .. graphviz:: - - graph { - user [ - shape=plaintext; - width=4; - label="User"; - style=""; - ] - view [ - shape=box; - width=4; - label=<View
Displaying the data>; - ] - controller [ - shape=box; - width=4; - label=<Controller
Control of functionality>; - ] - model [ - shape=box; - width=4; - label=<Model
Domain model and domain logic>; - ] - user -- view -- controller -- model; - } - - :ref:`Diagrams ` =================================== diff --git a/Documentation/WritingReST/Reference/Graphics/Graphs.rst b/Documentation/WritingReST/Reference/Graphics/Graphs.rst deleted file mode 100644 index 03979724..00000000 --- a/Documentation/WritingReST/Reference/Graphics/Graphs.rst +++ /dev/null @@ -1,484 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: - ! Graphs - Graphs; Graphviz -.. _graphviz-graphs: - -=============== -Graphviz graphs -=============== - -In order to render graphs in the TYPO3 documentation, -`Graphviz `_ is integrated into the rendering process. - -.. contents:: - :backlinks: top - :class: compact-list - :depth: 2 - :local: - -.. _graphviz-graphs-graph-types: - -Graph types -=========== - -There are two types of graphs to choose from: The directed and the undirected -graph, which are declared by the keywords `digraph` and `graph` respectively. - -.. index:: Graphs types; Undirected graph -.. _graphviz-graphs-undirected-graph: - -Undirected graph ----------------- - -.. graphviz:: - :caption: The MVC pattern divides the application into three global layers. - - graph { - user [ - shape=plaintext; - width=4; - label="User"; - style=""; - # Image is currently not supported due to a bug in Sphinx - # see https://github.com/sphinx-doc/sphinx/issues/8232#issuecomment-992711887 - # image="typo3-logo.svg"; - ] - view [ - shape=box; - width=4; - label=<View
Displaying the data>; - ] - controller [ - shape=box; - width=4; - label=<Controller
Control of functionality>; - ] - model [ - shape=box; - width=4; - label=<Model
Domain model and domain logic>; - ] - user -- view -- controller -- model; - } - -.. code-block:: rst - - .. graphviz:: - :caption: The MVC pattern divides the application into three global layers. - - graph { - user [ - shape=plaintext; - width=4; - label="User"; - style=""; - # Image is currently not supported due to a bug in Sphinx - # see https://github.com/sphinx-doc/sphinx/issues/8232#issuecomment-992711887 - # image="typo3-logo.svg"; - ] - view [ - shape=box; - width=4; - label=<View
Displaying the data>; - ] - controller [ - shape=box; - width=4; - label=<Controller
Control of functionality>; - ] - model [ - shape=box; - width=4; - label=<Model
Domain model and domain logic>; - ] - user -- view -- controller -- model; - } - -Examples: https://graphviz.org/Gallery/undirected/ - -.. index:: Graphs types; Directed graph -.. _graphviz-graphs-directed-graph: - -Directed graph --------------- - -.. graphviz:: - :caption: In this request, a list of blog posts is displayed. - - digraph { - graph [rankdir=BT;splines=ortho]; - node [shape=box;width=1]; - - user [label="User";shape=plaintext;style="";margin="0.36,0.055"]; - - subgraph cluster_view { - label="View"; - style="filled,dashed"; - v1 [label="V1"]; - v2 [label="V2";color=grey70;fillcolor=grey90;fontcolor=grey70]; - } - - subgraph cluster_controller { - label="Controller"; - style="filled,dashed"; - rankdir=LR; - - subgraph cluster_post_controller { - label="PostController"; - style=filled; - list []; - show [color=grey70;fillcolor=grey90;fontcolor=grey70]; - } - - subgraph cluster_comment_controller { - label="CommentController"; - style=filled; - color=grey70; - fillcolor=grey90; - fontcolor=grey70; - new [color=grey70;fillcolor=grey90;fontcolor=grey70]; - } - } - - subgraph cluster_model { - label="Model"; - rankdir=LR; - style="filled,dashed"; - blog_entity [label="";shape=ellipse]; - post_entity [label="";shape=ellipse]; - } - - blog_entity -> list [label="③ Array of blog posts"]; - list -> v1 [label="④ Array of blog posts for display"]; - v1 -> user [label="⑤ Response"]; - user -> list [label="① Request";constraint=false]; - list -> blog_entity [label="② Retrieve all blog posts";constraint=false]; - } - -.. code-block:: rst - - .. graphviz:: - :caption: In this request, a list of blog posts is displayed. - - digraph { - graph [rankdir=BT;splines=ortho]; - node [shape=box;width=1]; - - user [label="User";shape=plaintext;style="";margin="0.36,0.055"]; - - subgraph cluster_view { - label="View"; - style="filled,dashed"; - v1 [label="V1"]; - v2 [label="";style="";shape=plaintext]; - } - - subgraph cluster_controller { - label="Controller"; - style="filled,dashed"; - rankdir=LR; - - subgraph cluster_post_controller { - label="PostController"; - style=filled; - list []; - show [color=grey70;fillcolor=grey90;fontcolor=grey70]; - } - - subgraph cluster_comment_controller { - label="CommentController"; - style=filled; - color=grey70; - fillcolor=grey90; - fontcolor=grey70; - new [color=grey70;fillcolor=grey90;fontcolor=grey70]; - } - } - - subgraph cluster_model { - label="Model"; - rankdir=LR; - style="filled,dashed"; - blog_entity [label="";shape=ellipse]; - post_entity [label="";shape=ellipse]; - } - - blog_entity -> list [label="③ Array of blog posts"]; - list -> v1 [label="④ Array of blog posts for display"]; - v1 -> user [label="⑤ Response"]; - user -> list [label="① Request";constraint=false]; - list -> blog_entity [label="② Retrieve all blog posts";constraint=false]; - } - -Examples: https://graphviz.org/Gallery/directed/ - -.. _graphviz-graphs-layout-engines: - -Layout engines -============== - -The graphs can be rendered using different engines, where the default is -*Dot*, which is the most popular for directed graphs. -The engine is defined by the attribute `layout` with the available values - -- :ref:`dot ` (default) -- :ref:`neato ` -- :ref:`twopi ` -- :ref:`circo ` -- :ref:`fdp ` -- :ref:`osage ` -- :ref:`patchwork ` and -- :ref:`sfdp `. - -Below you will find some examples of graphs rendered by the available engines. - -.. index:: Graphs engines; Dot layout engine -.. _graphviz-graphs-dot-layout-engine: - -Dot layout engine ------------------ - -.. graphviz:: - - digraph G { - subgraph cluster_0 { - style=filled; - color=lightgrey; - fillcolor=lightgrey; - node [color=white;fillcolor=white]; - a0 -> a1 -> a2 -> a3; - label = "process #1"; - } - - subgraph cluster_1 { - b0 -> b1 -> b2 -> b3; - label="process #2"; - color=blue; - } - - start -> a0; - start -> b0; - a1 -> b3; - b2 -> a3; - a3 -> a0; - a3 -> end; - b3 -> end; - - start [shape=Mdiamond]; - end [shape=Msquare]; - } - -.. code-block:: rst - - .. graphviz:: - - digraph G { - subgraph cluster_0 { - style=filled; - color=lightgrey; - fillcolor=lightgrey; - node [color=white;fillcolor=white]; - a0 -> a1 -> a2 -> a3; - label = "process #1"; - } - - subgraph cluster_1 { - b0 -> b1 -> b2 -> b3; - label="process #2"; - color=blue; - } - - start -> a0; - start -> b0; - a1 -> b3; - b2 -> a3; - a3 -> a0; - a3 -> end; - b3 -> end; - - start [shape=Mdiamond]; - end [shape=Msquare]; - } - -Documentation: https://graphviz.org/docs/layouts/dot/ - -.. index:: Graphs engines; Neato layout engine -.. _graphviz-graphs-neato-layout-engine: - -Neato layout engine -------------------- - -.. graphviz:: - - graph ER { - layout=neato; - - node [shape=box]; course; institute; student; - node [shape=ellipse]; {node [label="name"] name0; name1; name2;} - code; grade; number; - node [shape=diamond,color=lightgrey,fillcolor=lightgrey]; "C-I"; "S-C"; "S-I"; - - name0 -- course; - code -- course; - course -- "C-I" [label="n",len=1.00]; - "C-I" -- institute [label="1",len=1.00]; - institute -- name1; - institute -- "S-I" [label="1",len=1.00]; - "S-I" -- student [label="n",len=1.00]; - student -- grade; - student -- name2; - student -- number; - student -- "S-C" [label="m",len=1.00]; - "S-C" -- course [label="n",len=1.00]; - - label="\n\nEntity Relation Diagram\ndrawn by NEATO"; - fontsize=20; - } - -.. code-block:: rst - - .. graphviz:: - - graph ER { - layout=neato; - - node [shape=box]; course; institute; student; - node [shape=ellipse]; {node [label="name"] name0; name1; name2;} - code; grade; number; - node [shape=diamond,color=lightgrey,fillcolor=lightgrey]; "C-I"; "S-C"; "S-I"; - - name0 -- course; - code -- course; - course -- "C-I" [label="n",len=1.00]; - "C-I" -- institute [label="1",len=1.00]; - institute -- name1; - institute -- "S-I" [label="1",len=1.00]; - "S-I" -- student [label="n",len=1.00]; - student -- grade; - student -- name2; - student -- number; - student -- "S-C" [label="m",len=1.00]; - "S-C" -- course [label="n",len=1.00]; - - label="\n\nEntity Relation Diagram\ndrawn by NEATO"; - fontsize=20; - } - -Documentation: https://graphviz.org/docs/layouts/neato/ - -.. index:: Graphs engines; Twopi layout engine -.. _graphviz-graphs-twopi-layout-engine: - -Twopi layout engine -------------------- - -The given examples of the Graphviz gallery are too large for inclusion here. -In case you can contribute one, feel encouraged to get in contact with us. -Navigate to the below URLs to get further insights. - -* Documentation: https://graphviz.org/docs/layouts/twopi/ -* Example: https://graphviz.org/Gallery/undirected/networkmap_twopi.html - -.. index:: Graphs engines; Circo layout engine -.. _graphviz-graphs-circo-layout-engine: - -Circo layout engine -------------------- - -No examples provided at the Graphviz gallery for this layout engine. -In case you can contribute one, feel encouraged to get in contact with us. -Navigate to the below URL to get further insights. - -Documentation: https://graphviz.org/docs/layouts/circo/ - -.. index:: Graphs engines; Fdp layout engine -.. _graphviz-graphs-fdp-layout-engine: - -Fdp layout engine ------------------ - -.. graphviz:: - - graph G { - layout=fdp; - - e; - - subgraph clusterA { - a -- b; - subgraph clusterC { - C -- D; - } - } - - subgraph clusterB { - d -- f; - } - - d -- D; - e -- clusterB; - clusterC -- clusterB; - } - -.. code-block:: rst - - .. graphviz:: - - graph G { - layout=fdp; - - e; - - subgraph clusterA { - a -- b; - subgraph clusterC { - C -- D; - } - } - - subgraph clusterB { - d -- f; - } - - d -- D; - e -- clusterB; - clusterC -- clusterB; - } - -.. index:: Graphs engines; Osage layout engine -.. _graphviz-graphs-osage-layout-engine: - -Osage layout engine -------------------- - -No examples provided at the Graphviz gallery for this layout engine. -In case you can contribute one, feel encouraged to get in contact with us. -Navigate to the below URL to get further insights. - -Documentation: https://graphviz.org/docs/layouts/osage/ - -.. index:: Graphs engines; Patchwork layout engine -.. _graphviz-graphs-patchwork-layout-engine: - -Patchwork layout engine ------------------------ - -No examples provided at the Graphviz gallery for this layout engine. -In case you can contribute one, feel encouraged to get in contact with us. -Navigate to the below URL to get further insights. - -Documentation: https://graphviz.org/docs/layouts/patchwork/ - -.. index:: Graphs engines; Sfdp layout engine -.. _graphviz-graphs-sfdp-layout-engine: - -Sfdp layout engine ------------------- - -No examples provided at the Graphviz gallery for this layout engine. -In case you can contribute one, feel encouraged to get in contact with us. -Navigate to the below URL to get further insights. - -Documentation: https://graphviz.org/docs/layouts/sfdp/ From 22c63ea0f5aca949215ff5d9c3145c5df8836093 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 30 Jan 2024 17:44:04 +0100 Subject: [PATCH 29/45] [TASK] Remove "common pitfalls" Displaying wrong syntax in order to teach someone is generally not considered best practise. Also some of these are specific to sphinx or outdated spinx versions. --- Documentation/GeneralConventions/Format.rst | 1 - .../WritingDocForExtension/Migrate.rst | 3 - .../WritingReST/CommonPitfalls/Headers.rst | 52 ---------- .../WritingReST/CommonPitfalls/Hyperlinks.rst | 71 -------------- .../WritingReST/CommonPitfalls/Indents.rst | 49 ---------- .../WritingReST/CommonPitfalls/Index.rst | 24 ----- .../CommonPitfalls/InlineStyle.rst | 45 --------- .../WritingReST/CommonPitfalls/Lists.rst | 94 ------------------- Documentation/WritingReST/Index.rst | 4 - .../Reference/Content/BoldItalic.rst | 10 +- .../Reference/Lists/BulletLists.rst | 63 +------------ 11 files changed, 4 insertions(+), 412 deletions(-) delete mode 100644 Documentation/WritingReST/CommonPitfalls/Headers.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Indents.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Index.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/InlineStyle.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Lists.rst diff --git a/Documentation/GeneralConventions/Format.rst b/Documentation/GeneralConventions/Format.rst index 296cc6e6..a3b95f90 100644 --- a/Documentation/GeneralConventions/Format.rst +++ b/Documentation/GeneralConventions/Format.rst @@ -88,7 +88,6 @@ readthedocs:: * indenting is important * new lines are important, for example before, after and between bullet lists - * more, see :ref:`rest-common-pitfalls` * some people simply hate it diff --git a/Documentation/WritingDocForExtension/Migrate.rst b/Documentation/WritingDocForExtension/Migrate.rst index 5198190b..c2d7da1f 100644 --- a/Documentation/WritingDocForExtension/Migrate.rst +++ b/Documentation/WritingDocForExtension/Migrate.rst @@ -51,9 +51,6 @@ Use our Docker container to render your documentation locally. Read more about Improve your documentation to render without warning ==================================================== -Have a look at :ref:`Common pitfalls ` that might cause -rendering warnings. - If you believe you found a bug in the new PHP-based rendering, please open an `Issue on GitHub `__. diff --git a/Documentation/WritingReST/CommonPitfalls/Headers.rst b/Documentation/WritingReST/CommonPitfalls/Headers.rst deleted file mode 100644 index 7367c433..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Headers.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Headers - -===================== -Problems with headers -===================== - -If you use section titles (headers), the underline must be **at least** as long as the text. - -Though you can make the underlines longer than the text, common practice -throughout the docs is to to keep it the same length. - -.. tip:: - - If you use an IDE with good reStructuredText support, it should point - out this error correctly, for example if you use PhpStorm, enable - the `reStructuredText plugin `__. - - -Correct syntax -============== - -.. code-block:: rst - - ================ - This Is a Header - ================ - - Another Header - ============== - - - This Is Also Correct but Not Recommended - ====================================================== - - -Wrong syntax -============ - - -.. code-block:: rst - - Another Header - ------------ - - -Additional information -====================== - -* :ref:`Headlines-and-sections` -* `reStructuredText Primer: Sections `__ diff --git a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst b/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst deleted file mode 100644 index 41975a53..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: reST; Hyperlinks -.. highlight:: rst - -=================== -Problems with links -=================== - -There are several ways to write links, here we assume you are -using external links with the following syntax. For more information -see the :ref:`references ` -at the bottom on this page. - -Correct syntax -============== - -.. code-block:: rst - - `anchor text `__ - - -Example: - -.. code-block:: rst - - `T3O `__ - -How this looks: - -`T3O `__ - - -Common mistake #1: Missing space -================================ - -Make sure there is a space between the anchor text and the -opening `<`. - - -Wrong syntax ------------- - -.. code-block:: rst - - Wrong: `T3O`__ - - Correct: `T3O `__ - - -Common mistake #2: Missing underscore (_) -========================================= - -Missing `_` or `__` at the end: - - -Wrong Syntax ------------- - -.. code-block:: rst - - Wrong: `T3O ` - - Correct: `T3O `__ - - -.. _common-pitfalls-links-more-information: - -Additional information -====================== - -* :ref:`external-links` diff --git a/Documentation/WritingReST/CommonPitfalls/Indents.rst b/Documentation/WritingReST/CommonPitfalls/Indents.rst deleted file mode 100644 index 721b0027..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Indents.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Indentation - -===================== -Problems with indents -===================== - - -Common mistake #1: Incorrect indents -==================================== - -Always indent correctly (4 spaces per level) - - -Correct syntax --------------- - -.. code-block:: rst - - .. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - -How it looks: - -.. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - - -Incorrect syntax ----------------- - -Here, `:width:` is indented with only 2 spaces. The image will not be -rendered at all! - -.. code-block:: rst - - .. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - -How it looks: - - -.. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow diff --git a/Documentation/WritingReST/CommonPitfalls/Index.rst b/Documentation/WritingReST/CommonPitfalls/Index.rst deleted file mode 100644 index 55590404..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Index.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Common pitfalls -.. _rest-common-pitfalls: - -=============== -Common pitfalls -=============== - -Here we describe some common mistakes. Read this section before you start -in order to avoid common errors. - -.. tip:: - - If you use an IDE with good reStructuredText support, it should point - out these errors correctly, for example if you use PhpStorm, enable - the `reStructuredText plugin `__. - - -.. toctree:: - :maxdepth: 2 - :glob: - - * diff --git a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst b/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst deleted file mode 100644 index 9721b90c..00000000 --- a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Inline styles -.. _common-pitfalls-inline-style: - -========================== -Problems with inline style -========================== - - -If you use **bold** or *italic*, make sure there is no space between -the markup and the styled text. - - -Correct syntax --------------- - -.. code-block:: rst - - This is normal text. **This is bold text.** - -How it looks: - - -This is normal text. **This is bold text.** - - -Wrong syntax ------------- - -.. code-block:: rst - - This is normal text. ** This is bold text.** - -How it looks: - - -This is normal text. ** This is bold text.** - - -Additional information -====================== - -* `Docutils cheat-sheet for reStructuredText: Inline markup - `__ diff --git a/Documentation/WritingReST/CommonPitfalls/Lists.rst b/Documentation/WritingReST/CommonPitfalls/Lists.rst deleted file mode 100644 index 7668328c..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Lists.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Lists - -=================== -Problems with lists -=================== - -If you use lists, make sure there is an empty line before and after the -list. If you use lists with sublevels, make sure there is an empty line -between the levels and the sublevel items are left-aligned with the -parent item text. - -The same applies for bullet lists and enumerated lists. - - -Correct syntax -============== - -Example 1: Bullet list -~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: rst - - this is some text - - * this is a list item - * another item - - more text - -**How it looks:** - -this is some text - -* this is a list item -* another item - -more text - - -Example 2: List with sublist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: rst - - this is some text - - * this is a list item - - * this is a sublevel list item - * another item - - this is more text - - -How it looks: - -this is some text - -* this is a list item - - * this is a sublevel list item - * another item - -this is more text - - -Wrong syntax ------------- - -.. code-block:: rst - - this is some text - * this is a list item - * another item - more text - -How it looks: - -this is some text -* this is a list item -* another item -more text - - -Additional information -====================== - -* `Docutils cheat-sheet for reStructuredText: Bullet list - `__ -* :ref:`Section on lists in this guide ` -* `Docutils cheat-sheet for reStructuredText: Enumerated lists - `__ diff --git a/Documentation/WritingReST/Index.rst b/Documentation/WritingReST/Index.rst index 3b3f3614..6b8b6f76 100644 --- a/Documentation/WritingReST/Index.rst +++ b/Documentation/WritingReST/Index.rst @@ -20,9 +20,6 @@ It is recommended to read (or at least browse through) the :ref:`writing-rest-introduction` and the general :ref:`format-rest-cgl` first. -Also read :ref:`rest-common-pitfalls` in order to avoid common -mistakes with the syntax. - You don't need to read the entire chapter, just lookup the section that is relevant for what you plan to do. @@ -48,6 +45,5 @@ http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_ Introduction BasicRestSyntax - CommonPitfalls/Index CheatSheet Reference/Index diff --git a/Documentation/WritingReST/Reference/Content/BoldItalic.rst b/Documentation/WritingReST/Reference/Content/BoldItalic.rst index 23a608ba..2676a936 100644 --- a/Documentation/WritingReST/Reference/Content/BoldItalic.rst +++ b/Documentation/WritingReST/Reference/Content/BoldItalic.rst @@ -35,14 +35,8 @@ How it looks: This is normal text. *This is italic text.* - -Possible Errors -=============== - -.. important:: - - Make sure there is no space between the markup and the styled text, - see :ref:`common-pitfalls-inline-style`. +.. hint:: + Make sure there is no space between the markup and the styled text. Additional Information diff --git a/Documentation/WritingReST/Reference/Lists/BulletLists.rst b/Documentation/WritingReST/Reference/Lists/BulletLists.rst index ad7b0e25..5c823db8 100644 --- a/Documentation/WritingReST/Reference/Lists/BulletLists.rst +++ b/Documentation/WritingReST/Reference/Lists/BulletLists.rst @@ -58,7 +58,6 @@ Example 1: List with sublist items **How it looks:** - * item 1 * item 2 is a longer text with line breaks. We can format and indent like this @@ -69,64 +68,6 @@ Example 1: List with sublist items * item 4 +.. note:: -Example 2: List with sublist and error -====================================== - -.. important:: - - This example will not work as expected, because the extra lines - for the sublist are missing. - -.. code-block:: rst - - * item 1 - * item 2 - * item 3 - * subitem 3.1 - * subitem 3.2 - * item 4 - -**How it looks:** - -* item 1 -* item 2 -* item 3 - * subitem 3.1 - * subitem 3.2 -* item 4 - - -Example 3: List with sublist and whitespace error -================================================= - -.. important:: - - Each asterix `*` has to be followed by three spaces. - If you only use one the sublist is interpreted like - a citation. - -.. code-block:: rst - - * item 1 - * item 2 - * item 3 - - * subitem 3.1 - * subitem 3.2 - - * item 4 - -**How it looks:** - -* item 1 -* item 2 -* item 3 - - * subitem 3.1 - * subitem 3.2 - -* item 4 - - -For more information on common errors, see :ref:`rest-common-pitfalls`. + Empty lines before and after the sublist are mandatory. From 4437f39c7b9b63dd650b5d2784e3909940b16b7c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 17:45:06 +0100 Subject: [PATCH 30/45] [TASK] Remove "common pitfalls" (#387) Displaying wrong syntax in order to teach someone is generally not considered best practise. Also some of these are specific to sphinx or outdated spinx versions. Co-authored-by: lina.wolf From c79b975a1fa604ed0b2d73c4e28385bb3db20a62 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 30 Jan 2024 18:26:18 +0100 Subject: [PATCH 31/45] [TASK] Remove Commit Messages conventions We do not have strict rules for commit messages. Where necessary we can refer to core rules, but we do not need to repeat them here. --- .../GeneralConventions/CommitMessages.rst | 128 ------------------ Documentation/GeneralConventions/Index.rst | 1 - Documentation/Maintainers/BackportChanges.rst | 3 +- Documentation/Maintainers/Changelog.rst | 2 - .../WritingDocsOfficial/LocalEditing.rst | 2 - 5 files changed, 1 insertion(+), 135 deletions(-) delete mode 100644 Documentation/GeneralConventions/CommitMessages.rst diff --git a/Documentation/GeneralConventions/CommitMessages.rst b/Documentation/GeneralConventions/CommitMessages.rst deleted file mode 100644 index de68313a..00000000 --- a/Documentation/GeneralConventions/CommitMessages.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: Git; Commit messages -.. _general-conventions-commit-messages: - -=============== -Commit messages -=============== - -The Documentation Team currently does not have strict "rules" for commit messages. These -are recommendations. - -Commit message recommendations -============================== - -* Write commit messages that are **clear**, **concise** and **meaningful** -* Use imperative form: "Fix typo" (instead of "Fixed typo"). This is - seen from the person, that is going to apply your patch: What will the patch do? - Fix typo! -* As in the TYPO3 core commit message rules, try to keep first line below 52 characters - if possible, but below 80 in any case. -* A commit message for the docs should consists of a subject line (first line). - More lines (separated by first line with an empty new line) are optional. - - -.. index:: Git; Resolves - -Issues ------- - -If an issue exists, link to it, by using for example "Resolves: #issue number", for example:: - - Resolves: #4 - -"Resolves" will automatically close the issue, using "Related" will not. - -You can also cross link to issues in other repositories in TYPO3-Documentation:: - - Related: TYPO3-Documentation/T3DocTeam#121 - -.. seealso:: - - * Stack Overflow: `Link to the issue number on GitHub within a commit message `__ - - -.. index:: Git; Releases - -Releases --------- - -If it should be backported to an older branch, use `Releases:` (as in :ref:`t3contribute:commitmessage`):: - - Releases: main, 11.5 - - -Examples -======== - -Example commit message with issue ---------------------------------- - -.. code-block:: none - - Add chapter for commit message rules - - Resolves: #4 - -This consists of the following parts: - -.. code-block:: none - - - - Resolves: # - -The issue number is optional. GitHub will automatically create a link to -the issue. - - -If you are editing online with GitHub, this may look like this: - -.. image:: /Images/commit-msg.png - :class: with-shadow - - - -Using "Resolves", will automatically close the issue. You can use "Related" instead of -"Resolves" if you do not want the issue to be closed. - -You can refer to more than one issue: - -.. code-block:: none - - - - Resolves: # - Resolves: # - -Add the branches to which the change should be added: - -.. code-block:: none - - - - Resolves: # - Releases: main, 11.5 - - -Using TYPO3 Core commit message rules -===================================== - -If you wish, you can use the prefixes [BUGFIX],[FEATURE],[TASK] etc. -as is customary in core development -(see :ref:`t3contribute:commitmessage`). - -However, this is not mandatory throughout the docs at the moment. If -possible, use the conventions, that are being used in -the manual in which you are working, for example `TYPO3 Explained commits -`__ -typically use these conventions. - - -Additional Information -====================== - -* `How to write a git commit message `__ -* :ref:`t3contribute:commitmessage` in TYPO3 Contribution Guide - Core Development - - diff --git a/Documentation/GeneralConventions/Index.rst b/Documentation/GeneralConventions/Index.rst index 2afa3879..05caa765 100644 --- a/Documentation/GeneralConventions/Index.rst +++ b/Documentation/GeneralConventions/Index.rst @@ -103,5 +103,4 @@ be found in the subchapters. Format CodingGuidelines GuidelinesForImages - CommitMessages Licenses diff --git a/Documentation/Maintainers/BackportChanges.rst b/Documentation/Maintainers/BackportChanges.rst index 4be3ccf5..6c4c2049 100644 --- a/Documentation/Maintainers/BackportChanges.rst +++ b/Documentation/Maintainers/BackportChanges.rst @@ -10,8 +10,7 @@ Backport changes Most of the time changes will be made to branch `main` and backported. When creating a pull request, it is possible to add a `Releases` line in the -:ref:`commit message ` -(as done in the Core): +commit message (as done in the Core): .. code-block:: text diff --git a/Documentation/Maintainers/Changelog.rst b/Documentation/Maintainers/Changelog.rst index 23ca82fd..7acbfd69 100644 --- a/Documentation/Maintainers/Changelog.rst +++ b/Documentation/Maintainers/Changelog.rst @@ -37,8 +37,6 @@ their commit message to the issue, for example Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790 Releases: main -See also: :ref:`general-conventions-commit-messages`. - .. index:: Documentation; Deprecations reST directives; deprecated diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 314b1f9d..044ba109 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -98,8 +98,6 @@ the ability to experiment and preview your changes locally before submitting the git commit -a Write a short, meaningful commit message describing what changes you have made. - See :ref:`general-conventions-commit-messages` for more information on how to - word your commit messages. 9. Push changes From 794994841a33402ac1ddc7d391180b22f62b83d0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 19:07:22 +0100 Subject: [PATCH 32/45] [TASK] Overhaul reST start page and menu structure (#392) Co-authored-by: lina.wolf --- Documentation/WritingReST/BasicRestSyntax.rst | 8 +-- Documentation/WritingReST/CheatSheet.rst | 6 +- Documentation/WritingReST/Index.rst | 62 ++++++++----------- Documentation/WritingReST/Reference/Index.rst | 6 +- 4 files changed, 35 insertions(+), 47 deletions(-) diff --git a/Documentation/WritingReST/BasicRestSyntax.rst b/Documentation/WritingReST/BasicRestSyntax.rst index df0d683f..1b08e071 100644 --- a/Documentation/WritingReST/BasicRestSyntax.rst +++ b/Documentation/WritingReST/BasicRestSyntax.rst @@ -3,11 +3,11 @@ .. index:: reST; Syntax .. _basic-rest-syntax: -========================== -Basic reST & Sphinx syntax -========================== +============================= +Basic reStructuredText syntax +============================= -The .rst files are written in reStructuredText (reST) format. They +The `.rst` files are written in reStructuredText (reST) format. They contain text with additional markup. diff --git a/Documentation/WritingReST/CheatSheet.rst b/Documentation/WritingReST/CheatSheet.rst index 1c953830..9ec82b2f 100644 --- a/Documentation/WritingReST/CheatSheet.rst +++ b/Documentation/WritingReST/CheatSheet.rst @@ -14,9 +14,9 @@ .. index:: reST; Cheat sheet .. _rest-cheat-sheet: -========================== -Cheat sheet: reST & Sphinx -========================== +============================= +Cheat sheet: reStructuredText +============================= :ref:`Headlines ` ========================================= diff --git a/Documentation/WritingReST/Index.rst b/Documentation/WritingReST/Index.rst index 6b8b6f76..09372633 100644 --- a/Documentation/WritingReST/Index.rst +++ b/Documentation/WritingReST/Index.rst @@ -1,49 +1,37 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: - ! reST - reStructuredText - see: reStructuredText; reST - ! Sphinx -.. _Formatting-with-reST: -.. _format-sphinx: -.. _rest-quick-start: - -========================= -reStructuredText & Sphinx -========================= - -This chapter is an introduction and reference for writing documentation using reStructuredText -(also referred to as reST) and Sphinx. +.. include:: /Includes.rst.txt +.. highlight:: rst +.. index:: + reStructuredText + reST +.. _Formatting-with-reST: +.. _format-sphinx: +.. _rest-quick-start: + +================ +reStructuredText +================ + +This chapter is an introduction and reference for writing documentation using +reStructuredText (also referred to as reST). It is recommended to read (or at least browse through) the :ref:`writing-rest-introduction` and the general :ref:`format-rest-cgl` first. -You don't need to read the entire chapter, just lookup -the section that is relevant for what you plan to do. - Or, use the :ref:`rest-cheat-sheet`, which contains the most commonly used markup on one page. -We won't be covering every reST markup that is +We cannot cover every reST markup that is available. For more information, see other resources, such as: -http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html - -.. tip:: - - See the t3SphinxThemeRtd demo docs for more examples. - - .. rst-class:: horizbuttons-striking-m - - - `➜ See the T3SphinxThemeRtd DemoDocs - `__ +* `reSTructuredText reference by Sphinx `__ +* `reSTructuredText introduction on docutils `__ +* `reStructuredText Markup Specification `__ -.. toctree:: - :hidden: +.. toctree:: + :hidden: - Introduction - BasicRestSyntax - CheatSheet - Reference/Index + Introduction + BasicRestSyntax + CheatSheet + Reference/Index diff --git a/Documentation/WritingReST/Reference/Index.rst b/Documentation/WritingReST/Reference/Index.rst index 2ff09136..a981a593 100644 --- a/Documentation/WritingReST/Reference/Index.rst +++ b/Documentation/WritingReST/Reference/Index.rst @@ -3,9 +3,9 @@ .. index:: reST; Reference .. _rest-reference: -======================== -Reference: reST & Sphinx -======================== +=========================== +Reference: reStructuredText +=========================== .. toctree:: :titlesonly: From ea85866cf737f10710f0d08f053d3ea79f96f450 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 31 Jan 2024 05:24:12 +0100 Subject: [PATCH 33/45] [Backport documentation-draft] [TASK] Simplify UML graphic examples (#396) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Simplify UML graphic examples * Update Documentation/WritingReST/Reference/Graphics/Diagrams.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/WritingReST/Reference/Graphics/Diagrams.rst --------- Co-authored-by: lina.wolf Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/WritingReST/CheatSheet.rst | 23 +- .../Reference/Graphics/Diagrams.rst | 718 +----------------- .../Reference/Graphics/_complex_uml.plantuml | 39 + 3 files changed, 70 insertions(+), 710 deletions(-) create mode 100644 Documentation/WritingReST/Reference/Graphics/_complex_uml.plantuml diff --git a/Documentation/WritingReST/CheatSheet.rst b/Documentation/WritingReST/CheatSheet.rst index 9ec82b2f..bdb92021 100644 --- a/Documentation/WritingReST/CheatSheet.rst +++ b/Documentation/WritingReST/CheatSheet.rst @@ -716,32 +716,19 @@ Source: **How it looks:** .. uml:: + :caption: Some Caption - == Initialization == - - Alice -> Bob: Authentication Request - Bob --> Alice: Authentication Response - - == Repetition == - - Alice -> Bob: Another authentication Request - Alice <-- Bob: another authentication Response + class -> otherClass : message Source: .. code-block:: rst + :caption: Documentation/SomeFile.rst .. uml:: + :caption: Some Caption - == Initialization == - - Alice -> Bob: Authentication Request - Bob --> Alice: Authentication Response - - == Repetition == - - Alice -> Bob: Another authentication Request - Alice <-- Bob: another authentication Response + class -> otherClass : message :ref:`Sidebar ` diff --git a/Documentation/WritingReST/Reference/Graphics/Diagrams.rst b/Documentation/WritingReST/Reference/Graphics/Diagrams.rst index d016de1b..340f741c 100644 --- a/Documentation/WritingReST/Reference/Graphics/Diagrams.rst +++ b/Documentation/WritingReST/Reference/Graphics/Diagrams.rst @@ -12,713 +12,47 @@ PlantUML diagrams In order to render diagrams in the TYPO3 documentation, `PlantUML `_ is integrated into the rendering process. -.. contents:: Types of diagrams: - :backlinks: top - :class: compact-list - :depth: 1 - :local: +Embedded UML diagrams +===================== -.. index:: Diagrams; Activity - -Activity diagram -================ - -.. uml:: - - (*) --> "ClickServlet.handleRequest()" - --> "new Page" - - if "Page.onSecurityCheck" then - ->[true] "Page.onInit()" - - if "isForward?" then - ->[no] "Process controls" - - if "continue processing?" then - -->[yes] ===RENDERING=== - else - -->[no] ===REDIRECT_CHECK=== - endif - else - -->[yes] ===RENDERING=== - endif - - if "is Post?" then - -->[yes] "Page.onPost()" - --> "Page.onRender()" as render - --> ===REDIRECT_CHECK=== - else - -->[no] "Page.onGet()" - --> render - endif - else - -->[false] ===REDIRECT_CHECK=== - endif - - if "Do redirect?" then - ->[yes] "redirect request" - --> ==BEFORE_DESTROY=== - else - if "Do Forward?" then - -left->[yes] "Forward request" - --> ==BEFORE_DESTROY=== - else - -right->[no] "Render page template" - --> ==BEFORE_DESTROY=== - endif - endif - - --> "Page.onDestroy()" - -->(*) - -.. code-block:: rst - - .. uml:: - - (*) --> "ClickServlet.handleRequest()" - --> "new Page" - - if "Page.onSecurityCheck" then - ->[true] "Page.onInit()" - - if "isForward?" then - ->[no] "Process controls" - - if "continue processing?" then - -->[yes] ===RENDERING=== - else - -->[no] ===REDIRECT_CHECK=== - endif - else - -->[yes] ===RENDERING=== - endif - - if "is Post?" then - -->[yes] "Page.onPost()" - --> "Page.onRender()" as render - --> ===REDIRECT_CHECK=== - else - -->[no] "Page.onGet()" - --> render - endif - else - -->[false] ===REDIRECT_CHECK=== - endif - - if "Do redirect?" then - ->[yes] "redirect request" - --> ==BEFORE_DESTROY=== - else - if "Do Forward?" then - -left->[yes] "Forward request" - --> ==BEFORE_DESTROY=== - else - -right->[no] "Render page template" - --> ==BEFORE_DESTROY=== - endif - endif - - --> "Page.onDestroy()" - -->(*) - -Docs: https://plantuml.com/activity-diagram-legacy - - -.. index:: Diagrams; Class - -Class diagram -============= - -.. uml:: - - class Foo1 { - You can use - several lines - .. - as you want - and group - == - things together. - __ - You can have as many groups - as you want - -- - End of class - } - - class User { - .. Simple Getter .. - + getName() - + getAddress() - .. Some setter .. - + setName() - __ private data __ - int age - -- encrypted -- - String password - } - -.. code-block:: rst - - .. uml:: - - class Foo1 { - You can use - several lines - .. - as you want - and group - == - things together. - __ - You can have as many groups - as you want - -- - End of class - } - - class User { - .. Simple Getter .. - + getName() - + getAddress() - .. Some setter .. - + setName() - __ private data __ - int age - -- encrypted -- - String password - } - -Docs: https://plantuml.com/class-diagram - -.. index:: Diagrams; Component - -Component diagram -================= - -.. uml:: - - package "Some Group" { - HTTP - [First Component] - [Another Component] - } - - node "Other Groups" { - FTP - [Second Component] - [First Component] --> FTP - } - - cloud { - [Example 1] - } - - database "MySql" { - folder "This is my folder" { - [Folder 3] - } - frame "Foo" { - [Frame 4] - } - } - - [Another Component] --> [Example 1] - [Example 1] --> [Folder 3] - [Folder 3] --> [Frame 4] - -.. code-block:: rst - - .. uml:: - - package "Some Group" { - HTTP - [First Component] - [Another Component] - } - - node "Other Groups" { - FTP - [Second Component] - [First Component] --> FTP - } - - cloud { - [Example 1] - } - - database "MySql" { - folder "This is my folder" { - [Folder 3] - } - frame "Foo" { - [Frame 4] - } - } - - [Another Component] --> [Example 1] - [Example 1] --> [Folder 3] - [Folder 3] --> [Frame 4] - -Docs: https://plantuml.com/component-diagram - -.. index:: Diagrams; Deployment - -Deployment diagram -================== - -.. uml:: - - artifact Foo1 { - folder Foo2 - } - - folder Foo3 { - artifact Foo4 - } - - frame Foo5 { - database Foo6 - } - - cloud vpc { - node ec2 { - stack stack - } - } +Simple diagrams can be embedded directly into the reStructuredText markup: .. code-block:: rst + :caption: Documentation/SomeFile.rst .. uml:: + :caption: Some Caption - artifact Foo1 { - folder Foo2 - } + class -> otherClass : message - folder Foo3 { - artifact Foo4 - } - - frame Foo5 { - database Foo6 - } - - cloud vpc { - node ec2 { - stack stack - } - } - -Docs: https://plantuml.com/deployment-diagram - - -.. index:: pair:Diagrams; Icons - -Icons -===== - -There are two ways to integrate icons into your diagrams: Either by using the -supplied *PlantUML Standard Library*, which comes with a suitable set of symbols, -or by using remote font sets. The standard library can be used for offline -rendering, while the remote font sets always contain the latest symbols. - -Standard Library ----------------- - -The PlantUML Standard Library contains dumps of various well-known third-party -font sets such as Font Awesome (v4 and v5), Devicon, etc. The available icons -can best be searched by checking out the `project repository -`_ -with the release date of PlantUML v2018.13, which is used in the current -rendering process of the TYPO3 documentation. +This will be rendered as: .. uml:: + :caption: Some Caption - !include - !include - !include - !include - !include - !include - !include - !include - - skinparam defaultTextAlignment center - - rectangle "<$elasticsearch>\nElastic\nSearch" as elastic - rectangle "<$haproxy>\nHAProxy" as haproxy - - DEV_MYSQL(mysql,Mysql,database) - DEV_NGINX(nginx,Nginx,rectangle) - DEV_NGINX(nginx2,Nginx,rectangle) - DEV_PHP(php,PHP + TYPO3,rectangle) - DEV_PHP(php2,PHP + TYPO3,rectangle) - DEV_REDIS(redis,Redis,database) - - FA5_TYPO3(typo3,TYPO3\nShared,rectangle,#f49700) + class -> otherClass : message - haproxy <--> nginx - haproxy <--> nginx2 - nginx <--> php - nginx2 <--> php2 - php <--> typo3 - php <--> redis - php <--> mysql - php <--> elastic - php2 <--> typo3 - php2 <--> redis - php2 <--> mysql - php2 <--> elastic +Include a PlantUML file +======================= .. code-block:: rst + :caption: Documentation/SomeFile.rst - .. uml:: - - !include - !include - !include - !include - !include - !include - !include - !include - - skinparam defaultTextAlignment center - - rectangle "<$elasticsearch>\nElastic\nSearch" as elastic - rectangle "<$haproxy>\nHAProxy" as haproxy - - DEV_MYSQL(mysql,Mysql,database) - DEV_NGINX(nginx,Nginx,rectangle) - DEV_NGINX(nginx2,Nginx,rectangle) - DEV_PHP(php,PHP + TYPO3,rectangle) - DEV_PHP(php2,PHP + TYPO3,rectangle) - DEV_REDIS(redis,Redis,database) - - FA5_TYPO3(typo3,TYPO3\nShared,rectangle,#f49700) - - haproxy <--> nginx - haproxy <--> nginx2 - nginx <--> php - nginx2 <--> php2 - php <--> typo3 - php <--> redis - php <--> mysql - php <--> elastic - php2 <--> typo3 - php2 <--> redis - php2 <--> mysql - php2 <--> elastic - - -Remote font sets ----------------- - -.. note:: - - Including icons this way requires an online connection during the rendering - process. - -The latest icons can be integrated directly via remote url. - -.. uml:: - - !define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0 - !includeurl ICONURL/common.puml - !includeurl ICONURL/devicons/typo3.puml - - DEV_TYPO3(typo3,"TYPO3",participant,orange) - -.. code-block:: rst - - .. uml:: - - !define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0 - !includeurl ICONURL/common.puml - !includeurl ICONURL/devicons/typo3.puml - - DEV_TYPO3(typo3,"TYPO3",participant,orange) - -Docs: https://plantuml.com/stdlib - - -.. index:: pair: Diagrams; Maths + .. uml:: _complex_uml.plantuml + :align: center + :caption: Figure 1-1: Application flow + :width: 1000 -Maths -===== - -.. uml:: - - :int_0^1f(x)dx; - :x^2+y_1+z_12^34; - note right - Try also - d/dxf(x)=lim_(h->0)(f(x+h)-f(x))/h - P(y|\mathbf{x}) \mbox{ or } f(\mathbf{x})+\epsilon - end note - -.. code-block:: rst - - .. uml:: - - :int_0^1f(x)dx; - :x^2+y_1+z_12^34; - note right - Try also - d/dxf(x)=lim_(h->0)(f(x+h)-f(x))/h - P(y|\mathbf{x}) \mbox{ or } f(\mathbf{x})+\epsilon - end note - -Docs: https://plantuml.com/ascii-math - - -Misc -==== - -.. uml:: - - title My title - header My header - footer My footer - - actor Bob [[http://plantuml.com/sequence]] - actor "This is [[http://plantuml.com/sequence Alice]] actor" as Alice - Bob -> Alice [[http://plantuml.com/start]] : hello - Alice -> Bob : hello with [[http://plantuml.com/start{Tooltip for message} some link]] - note left of Bob - You can use [[http://plantuml.com/start links in notes]] also. - end note - -.. code-block:: rst - - .. uml:: - - title My title - header My header - footer My footer - - actor Bob [[http://plantuml.com/sequence]] - actor "This is [[http://plantuml.com/sequence Alice]] actor" as Alice - Bob -> Alice [[http://plantuml.com/start]] : hello - Alice -> Bob : hello with [[http://plantuml.com/start{Tooltip for message} some link]] - note left of Bob - You can use [[http://plantuml.com/start links in notes]] also. - end note - -Docs: https://plantuml.com/link | https://plantuml.com/sequence-diagram - - -.. index:: Diagrams; Object - -Object diagram -============== - -.. uml:: - - object Object01 { - name = "Dummy" - id = 123 - } - object Object02 - object Object03 - object Object04 - object Object05 - object Object06 - object Object07 - object Object08 - - Object01 <|-- Object02 - Object03 *-- Object04 - Object05 o-- "4" Object06 - Object07 .. Object08 : some labels - -.. code-block:: rst - - .. uml:: - - object Object01 { - name = "Dummy" - id = 123 - } - object Object02 - object Object03 - object Object04 - object Object05 - object Object06 - object Object07 - object Object08 - - Object01 <|-- Object02 - Object03 *-- Object04 - Object05 o-- "4" Object06 - Object07 .. Object08 : some labels - -Docs: https://plantuml.com/object-diagram - - -.. index:: Diagrams; Sequence - -Sequence diagram -================ - -.. uml:: - - == Initialization == - - Alice -> Bob: Authentication Request - Bob --> Alice: Authentication Response - - == Repetition == - - Alice -> Bob: Another authentication Request - Alice <-- Bob: another authentication Response - -.. code-block:: rst - - .. uml:: - - == Initialization == - - Alice -> Bob: Authentication Request - Bob --> Alice: Authentication Response - - == Repetition == - - Alice -> Bob: Another authentication Request - Alice <-- Bob: another authentication Response - -Docs: https://plantuml.com/sequence-diagram - - -.. index:: Diagrams; State - -State diagram -============= - -.. uml:: - - [*] --> NotShooting - - state NotShooting { - [*] --> Idle - Idle --> Configuring : EvConfig - Configuring --> Idle : EvConfig - } - - state Configuring { - [*] --> NewValueSelection - NewValueSelection --> NewValuePreview : EvNewValue - NewValuePreview --> NewValueSelection : EvNewValueRejected - NewValuePreview --> NewValueSelection : EvNewValueSaved - - state NewValuePreview { - State1 -> State2 - } - } - -.. code-block:: rst - - .. uml:: - - [*] --> NotShooting - - state NotShooting { - [*] --> Idle - Idle --> Configuring : EvConfig - Configuring --> Idle : EvConfig - } - - state Configuring { - [*] --> NewValueSelection - NewValueSelection --> NewValuePreview : EvNewValue - NewValuePreview --> NewValueSelection : EvNewValueRejected - NewValuePreview --> NewValueSelection : EvNewValueSaved - - state NewValuePreview { - State1 -> State2 - } - } - -Docs: https://plantuml.com/state-diagram - - -.. index:: Diagrams; Timing - -Timing diagram -============== - -.. uml:: - - robust "Web Browser" as WB - concise "Web User" as WU - - WB is Initializing - WU is Absent - - @WB - 0 is idle - +200 is Processing - +100 is Waiting - WB@0 <-> @50 : {50 ms lag} - - @WU - 0 is Waiting - +500 is ok - @200 <-> @+150 : {150 ms} - -.. code-block:: rst - - .. uml:: - - robust "Web Browser" as WB - concise "Web User" as WU - - WB is Initializing - WU is Absent - - @WB - 0 is idle - +200 is Processing - +100 is Waiting - WB@0 <-> @50 : {50 ms lag} - - @WU - 0 is Waiting - +500 is ok - @200 <-> @+150 : {150 ms} - -Docs: https://plantuml.com/timing-diagram - - -.. index:: Diagrams; Use case - -Use Case diagram -================ - -.. uml:: - - left to right direction - skinparam packageStyle rectangle - - actor customer - actor clerk - rectangle checkout { - customer -- (checkout) - (checkout) .> (payment) : include - (help) .> (checkout) : extends - (checkout) -- clerk - } - -.. code-block:: rst - - .. uml:: +This will be rendered as: - left to right direction - skinparam packageStyle rectangle +.. uml:: _complex_uml.plantuml + :align: center + :caption: Figure 1-1: Application flow + :width: 1000 - actor customer - actor clerk - rectangle checkout { - customer -- (checkout) - (checkout) .> (payment) : include - (help) .> (checkout) : extends - (checkout) -- clerk - } +Put a file called :file:`_complex_uml.plantuml` in the same directory as +the reST file: -Docs: https://plantuml.com/use-case-diagram +.. literalinclude:: _complex_uml.plantuml + :caption: Documentation/_complex_uml.plantuml + :language: text diff --git a/Documentation/WritingReST/Reference/Graphics/_complex_uml.plantuml b/Documentation/WritingReST/Reference/Graphics/_complex_uml.plantuml new file mode 100644 index 00000000..413ce430 --- /dev/null +++ b/Documentation/WritingReST/Reference/Graphics/_complex_uml.plantuml @@ -0,0 +1,39 @@ +enum FeedFormat { + ATOM + JSON + RSS +} + +interface AuthorInterface +interface CategoryInterface +interface FeedInterface +interface FeedFormatAwareInterface +interface ImageInterface +interface ItemInterface +interface RequestAwareInterface + +class Author +class Image +class Item + +class YourFeed +note left: This is your feed implementation class + +YourFeed -[hidden]> FeedFormat + +Author <|.. AuthorInterface +Category <|.. CategoryInterface +Image <|.. ImageInterface +Item <|.. ItemInterface + +FeedInterface ..|> YourFeed : required +FeedFormatAwareInterface ..|> YourFeed : optional +RequestAwareInterface ..|> YourFeed : optional + +Item "1" *-- "0 .. n" Author : contains + +YourFeed "1" *-- "0 .. n" Author : contains +YourFeed "1" *-- "0 .. n" Category : contains +YourFeed "1" *-- "0 .. 1" Image : contains +YourFeed "1" *-- "0 .. n" Item : contains +YourFeed .. FeedFormat : used in attributes From 19bf899705f1ec168a5409420b68abb906984786 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Thu, 1 Feb 2024 05:11:08 +0000 Subject: [PATCH 34/45] [TASK] Add legacy installation to major Core version adjustments (#397) (cherry picked from commit b176a024e5cfeb2d9c8a6d3e200b9937b3b1ce67) --- Documentation/Maintainers/NewMajorCoreVersion.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/Maintainers/NewMajorCoreVersion.rst b/Documentation/Maintainers/NewMajorCoreVersion.rst index c8805951..24410417 100644 --- a/Documentation/Maintainers/NewMajorCoreVersion.rst +++ b/Documentation/Maintainers/NewMajorCoreVersion.rst @@ -15,7 +15,8 @@ The section describes the doings when a new major Core version is released To do ===== -* Update :ref:`t3start:install` to reflect the new version upon installation. +* Update :ref:`t3start:install` and :ref:`t3start:legacyinstallation` to + reflect the new version upon installation. * Add "-dev" links (like `13-dev`) to the links on the homepage: From d87d65239e3a2a63733c29d276f9cd7449215d07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 5 Feb 2024 15:32:17 +0000 Subject: [PATCH 35/45] [TASK] Add more pages to adjust with a new Core major version (#398) (cherry picked from commit 4b2b87bb6d7cb07de01253320c76a2598dcbd6bc) --- Documentation/Maintainers/NewMajorCoreVersion.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Documentation/Maintainers/NewMajorCoreVersion.rst b/Documentation/Maintainers/NewMajorCoreVersion.rst index 24410417..b3f6062a 100644 --- a/Documentation/Maintainers/NewMajorCoreVersion.rst +++ b/Documentation/Maintainers/NewMajorCoreVersion.rst @@ -15,8 +15,14 @@ The section describes the doings when a new major Core version is released To do ===== -* Update :ref:`t3start:install` and :ref:`t3start:legacyinstallation` to - reflect the new version upon installation. +* Update + + * :ref:`t3start:install` + * :ref:`t3start:legacyinstallation` + * :ref:`t3start:installation-ddev-tutorial` + * :ref:`t3install:upgradecore` + + to reflect the new version upon installation/upgrade. * Add "-dev" links (like `13-dev`) to the links on the homepage: From eb738e43f984bea7197cd43a0600b0042ab64123 Mon Sep 17 00:00:00 2001 From: Philipp Kuhlmay <107543296+PKuhlmay@users.noreply.github.com> Date: Tue, 20 Feb 2024 13:14:04 +0100 Subject: [PATCH 36/45] Use correct article for the word "attention" (#399) For the word attention, the article "an" is used, instead of "a", because attention starts with a vowel. (cherry picked from commit 363a439ecb76b9f77cbe79a3e767c560f0b7b1c1) --- Documentation/WritingReST/Reference/Content/Admonitions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/WritingReST/Reference/Content/Admonitions.rst b/Documentation/WritingReST/Reference/Content/Admonitions.rst index 5489bc40..abb392a9 100644 --- a/Documentation/WritingReST/Reference/Content/Admonitions.rst +++ b/Documentation/WritingReST/Reference/Content/Admonitions.rst @@ -83,10 +83,10 @@ Attention .. code-block:: rst .. attention:: - A attention + An attention .. attention:: - A attention + An attention More Information From d593d6ff6516c24c2ac34049c01f28f70d590329 Mon Sep 17 00:00:00 2001 From: Franz Holzinger Date: Sat, 24 Feb 2024 07:18:18 +0100 Subject: [PATCH 37/45] The REST README must not be in markdown (#400) * The REST README must not be in markdown There is a markdown table which does not work in REST. * use samp method around links * fix headers to REST * headers (cherry picked from commit 2384f2ea07976b8257f6578588f22d773b7146fc) --- .../FileStructure/ReadmeRstStandalone.rst.txt | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/Documentation/CodeSnippets/FileStructure/ReadmeRstStandalone.rst.txt b/Documentation/CodeSnippets/FileStructure/ReadmeRstStandalone.rst.txt index ea75a1da..c69682b4 100644 --- a/Documentation/CodeSnippets/FileStructure/ReadmeRstStandalone.rst.txt +++ b/Documentation/CodeSnippets/FileStructure/ReadmeRstStandalone.rst.txt @@ -3,21 +3,28 @@ - # + ========= + + ========= - ## Installation + Installation + ============ .. - ## Configuration + Configuration + ============= .. - ## Usage + Usage + ====== .. - | | URL | - |------------------|---------------------------------------------------------------| - | **Repository:** | https:// | - | **Read online:** | https://docs.typo3.org/p//main/en-us/ | - | **TER:** | https://extensions.typo3.org/extension// | + .. csv-table:: + :header: "", "URL" + + **Repository:**, :samp:`https://{}` + **Read online:**, :samp:`https://docs.typo3.org/p/{}/main/en-us/` + **TER:**, :samp:`https://extensions.typo3.org/extension/{}/` + From 8b50cc63d50dc7544d11550c4e0a3e335e8d8397 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Sat, 2 Mar 2024 08:05:45 +0000 Subject: [PATCH 38/45] [TASK] Provide list of available languages for code blocks (#401) --- .../WritingReST/Reference/Code/Codeblocks.rst | 450 +----------------- 1 file changed, 13 insertions(+), 437 deletions(-) diff --git a/Documentation/WritingReST/Reference/Code/Codeblocks.rst b/Documentation/WritingReST/Reference/Code/Codeblocks.rst index 8dbca316..36667bb0 100644 --- a/Documentation/WritingReST/Reference/Code/Codeblocks.rst +++ b/Documentation/WritingReST/Reference/Code/Codeblocks.rst @@ -85,11 +85,11 @@ will fail. The language of the code-block. We commonly use the following: :rst:`php`, - :rst:`typoscript` (also for tsconfig), :rst:`yaml`, :rst:`javascript`, - :rst:`html` (also for Fluid), :rst:`shell`, :rst:`xml`, :rst:`none`. + :rst:`typoscript` (also for TSconfig), :rst:`yaml`, :rst:`javascript`, + :rst:`html` (also for Fluid), :rst:`shell`, :rst:`xml`, :rst:`plaintext`. See all - :ref:`available lexers ` + :ref:`available languages ` To make orientation in code examples easier try to always add @@ -336,442 +336,18 @@ imports the :file:`Documentation/Includes.rst.txt` file at the top. And in the included file - in general - we set PHP as default language for highlighting. Exception: In the TypoScript manuals we are using `typoscript` as default. -.. index:: reST; Lexers +.. index:: reST; Languages +.. _writing-rest-codeblocks-available-languages: .. _writing-rest-codeblocks-available-lexers: -Available lexers -================ - -You can use any of the following names of lexers: - - -`| bash, sh, ksh, shell |` for example all mean the same lexer: - -abap \| -abnf \| -ada, ada95, ada2005 \| -adl \| -agda \| -ahk, autohotkey \| -alloy \| -ampl \| -antlr-as, antlr-actionscript \| -antlr-cpp \| -antlr-csharp, antlr-c# \| -antlr-java \| -antlr-objc \| -antlr-perl \| -antlr-python \| -antlr-ruby, antlr-rb \| -antlr \| -apacheconf, aconf, apache \| -apl \| -applescript \| -arduino \| -as, actionscript \| -as3, actionscript3 \| -aspectj \| -aspx-cs \| -aspx-vb \| -asy, asymptote \| -at, ambienttalk, ambienttalk/2 \| -autoit \| -awk, gawk, mawk, nawk \| -basemake \| -bash, sh, ksh, shell \| -bat, batch, dosbatch, winbatch \| -bbcode \| -bc \| -befunge \| -blitzbasic, b3d, bplus \| -blitzmax, bmax \| -bnf \| -boo \| -boogie \| -brainfuck, bf \| -bro \| -bugs, winbugs, openbugs \| -c-objdump \| -c \| -ca65 \| -cadl \| -camkes, idl4 \| -cbmbas \| -ceylon \| -cfc \| -cfengine3, cf3 \| -cfm \| -cfs \| -chai, chaiscript \| -chapel, chpl \| -cheetah, spitfire \| -cirru \| -clay \| -clean \| -clojure, clj \| -clojurescript, cljs \| -cmake \| -cobol \| -cobolfree \| -coffee-script, coffeescript, coffee \| -common-lisp, cl, lisp \| -componentpascal, cp \| -console, shell-session \| -control, debcontrol \| -coq \| -cpp, c++ \| -cpp-objdump, c++-objdumb, cxx-objdump \| -cpsa \| -crmsh, pcmk \| -croc \| -cryptol, cry \| -csharp, c# \| -csound, csound-orc \| -csound-document, csound-csd \| -csound-score, csound-sco \| -css+django, css+jinja \| -css+erb, css+ruby \| -css+genshitext, css+genshi \| -css+lasso \| -css+mako \| -css+mako \| -css+mozpreproc \| -css+myghty \| -css+php \| -css+smarty \| -css \| -cucumber, gherkin \| -cuda, cu \| -cypher \| -cython, pyx, pyrex \| -d-objdump \| -d \| -dart \| -delphi, pas, pascal, objectpascal \| -dg \| -diff, udiff \| -django, jinja \| -docker, dockerfile \| -doscon \| -dpatch \| -dtd \| -duel, jbst, jsonml+bst \| -dylan-console, dylan-repl \| -dylan-lid, lid \| -dylan \| -earl-grey, earlgrey, eg \| -easytrieve \| -ebnf \| -ec \| -ecl \| -eiffel \| -elixir, ex, exs \| -elm \| -emacs, elisp, emacs-lisp \| -erb \| -erl \| -erlang \| -evoque \| -extempore \| -ezhil \| -factor \| -fan \| -fancy, fy \| -felix, flx \| -fish, fishshell \| -flatline \| -fortran \| -fortranfixed \| -foxpro, vfp, clipper, xbase \| -fsharp \| -gap \| -gas, asm \| -genshi, kid, xml+genshi, xml+kid \| -genshitext \| -glsl \| -gnuplot \| -go \| -golo \| -gooddata-cl \| -gosu \| -groff, nroff, man \| -groovy \| -gst \| -haml \| -handlebars \| -haskell, hs \| -haxeml, hxml \| -hexdump \| -hsail, hsa \| -html+cheetah, html+spitfire, htmlcheetah \| -html+django, html+jinja, htmldjango \| -html+evoque \| -html+genshi, html+kid \| -html+handlebars \| -html+lasso \| -html+mako \| -html+mako \| -html+myghty \| -html+php \| -html+smarty \| -html+twig \| -html+velocity \| -html \| -http \| -hx, haxe, hxsl \| -hybris, hy \| -hylang \| -i6t \| -idl \| -idris, idr \| -iex \| -igor, igorpro \| -inform6, i6 \| -inform7, i7 \| -ini, cfg, dosini \| -io \| -ioke, ik \| -irc \| -isabelle \| -j \| -jade \| -jags \| -jasmin, jasminxt \| -java \| -javascript+mozpreproc \| -jcl \| -jlcon \| -js+cheetah, javascript+cheetah, js+spitfire, javascript+spitfire \| -js+django, javascript+django, js+jinja, javascript+jinja \| -js+erb, javascript+erb, js+ruby, javascript+ruby \| -js+genshitext, js+genshi, javascript+genshitext, javascript+genshi \| -js+lasso, javascript+lasso \| -js+mako, javascript+mako \| -js+mako, javascript+mako \| -js+myghty, javascript+myghty \| -js+php, javascript+php \| -js+smarty, javascript+smarty \| -js, javascript \| -jsgf \| -json \| -jsonld, json-ld \| -jsp \| -julia, jl \| -kal \| -kconfig, menuconfig, linux-config, kernel-config \| -koka \| -kotlin \| -lagda, literate-agda \| -lasso, lassoscript \| -lcry, literate-cryptol, lcryptol \| -lean \| -less \| -lhs, literate-haskell, lhaskell \| -lidr, literate-idris, lidris \| -lighty, lighttpd \| -limbo \| -liquid \| -live-script, livescript \| -llvm \| -logos \| -logtalk \| -lsl \| -lua \| -make, makefile, mf, bsdmake \| -mako \| -mako \| -maql \| -mask \| -mason \| -mathematica, mma, nb \| -matlab \| -matlabsession \| -minid \| -modelica \| -modula2, m2 \| -monkey \| -moocode, moo \| -moon, moonscript \| -mozhashpreproc \| -mozpercentpreproc \| -mql, mq4, mq5, mql4, mql5 \| -mscgen, msc \| -mupad \| -mxml \| -myghty \| -mysql \| -nasm \| -ncl \| -nemerle \| -nesc \| -newlisp \| -newspeak \| -nginx \| -nimrod, nim \| -nit \| -nixos, nix \| -nsis, nsi, nsh \| -numpy \| -objdump-nasm \| -objdump \| -objective-c++, objectivec++, obj-c++, objc++ \| -objective-c, objectivec, obj-c, objc \| -objective-j, objectivej, obj-j, objj \| -ocaml \| -octave \| -odin \| -ooc \| -opa \| -openedge, abl, progress \| -pacmanconf \| -pan \| -parasail \| -pawn \| -perl, pl \| -perl6, pl6 \| -php, php3, php4, php5 \| -pig \| -pike \| -pkgconfig \| -plpgsql \| -postgresql, postgres \| -postscript, postscr \| -pot, po \| -pov \| -powershell, posh, ps1, psm1 \| -praat \| -prolog \| -properties, jproperties \| -protobuf, proto \| -ps1con \| -psql, postgresql-console, postgres-console \| -puppet \| -py3tb \| -pycon \| -pypylog, pypy \| -pytb \| -python, py, sage \| -python3, py3 \| -qbasic, basic \| -qml, qbs \| -qvto, qvt \| -racket, rkt \| -ragel-c \| -ragel-cpp \| -ragel-d \| -ragel-em \| -ragel-java \| -ragel-objc \| -ragel-ruby, ragel-rb \| -ragel \| -raw \| -rb, ruby, duby \| -rbcon, irb \| -rconsole, rout \| -rd \| -rebol \| -red, red/system \| -redcode \| -registry \| -resource, resourcebundle \| -rexx, arexx \| -rhtml, html+erb, html+ruby \| -roboconf-graph \| -roboconf-instances \| -robotframework \| -rql \| -rsl \| -rst, rest, restructuredtext \| -rts, trafficscript \| -rust \| -sass \| -sc, supercollider \| -scala \| -scaml \| -scheme, scm \| -scilab \| -scss \| -shen \| -silver \| -slim \| -smali \| -smalltalk, squeak, st \| -smarty \| -sml \| -snobol \| -sourceslist, sources.list, debsources \| -sp \| -sparql \| -spec \| -splus, s, r \| -sql \| -sqlite3 \| -squidconf, squid.conf, squid \| -ssp \| -stan \| -swift \| -swig \| -systemverilog, sv \| -tads3 \| -tap \| -tcl \| -tcsh, csh \| -tcshcon \| -tea \| -termcap \| -terminfo \| -terraform, tf \| -tex, latex \| -text \| -thrift \| -todotxt \| -trac-wiki, moin \| -treetop \| -ts, typescript \| -turtle \| -twig \| -typoscript \| -typoscriptcssdata \| -typoscripthtmldata \| -urbiscript \| -vala, vapi \| -vb.net, vbnet \| -vcl \| -vclsnippets, vclsnippet \| -vctreestatus \| -velocity \| -verilog, v \| -vgl \| -vhdl \| -vim \| -wdiff \| -x10, xten \| -xml+cheetah, xml+spitfire \| -xml+django, xml+jinja \| -xml+erb, xml+ruby \| -xml+evoque \| -xml+lasso \| -xml+mako \| -xml+mako \| -xml+myghty \| -xml+php \| -xml+smarty \| -xml+velocity \| -xml \| -xquery, xqy, xq, xql, xqm \| -xslt \| -xtend \| -xul+mozpreproc \| -yaml+jinja, salt, sls \| -yaml \| -zephir \| - -**Tip:** Try the Pygments Demo at http://pygments.org/ - - -`Sphinx `__ uses `Pygments -`__ for highlighting. On a machine that has Pygments -installed the command `pygmentize -L` will list all available lexers. +Available languages +=================== + +The following languages are supported. They can be used in a :rst:`code-block` +and a :rst:`literalinclude` directive. + +.. guides:codeblock-languages:: + Literalinclude ============== From af03f59d47b15e3b698fbba3e0d21609d805ae9b Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 12 Mar 2024 14:27:04 +0100 Subject: [PATCH 39/45] [TASK] Fix php-based rendering warnings 1: Add ":orphan:" to the ReadmeFile. Don't know where this is linked to. Maybe this can be removed (in a follow-up) 2: Remove usage-version-selector reference, this no longer exists on the DocsHome repository --- Documentation/GeneralConventions/ReadmeFile.rst | 2 +- Documentation/WritingDocsOfficial/HowYouCanHelp.rst | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/GeneralConventions/ReadmeFile.rst b/Documentation/GeneralConventions/ReadmeFile.rst index 06339544..3a5061e9 100644 --- a/Documentation/GeneralConventions/ReadmeFile.rst +++ b/Documentation/GeneralConventions/ReadmeFile.rst @@ -1,4 +1,4 @@ - +:orphan: .. index:: File structure; README.rst, README.rst .. _readme-rst: .. _about-file: diff --git a/Documentation/WritingDocsOfficial/HowYouCanHelp.rst b/Documentation/WritingDocsOfficial/HowYouCanHelp.rst index 725dce6a..a0849e8b 100644 --- a/Documentation/WritingDocsOfficial/HowYouCanHelp.rst +++ b/Documentation/WritingDocsOfficial/HowYouCanHelp.rst @@ -172,8 +172,7 @@ the changes yourself. More information: :ref:`guidelines-for-reviewing` .. tip:: - Usually, there is - :ref:`one branch for each major TYPO3 version ` + Usually, there is one branch for each major TYPO3 version in a manual. Please focus your efforts mostly on the "main" branch, to get that up to date and ready! The Documentation Team will then check, if a backport to older versions makes sense. From 48f0daa70e1c6b9dd52cd5f9586e250a4fe53244 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Wed, 13 Mar 2024 22:30:44 +0100 Subject: [PATCH 40/45] [TASK] Add in-depth notes for migration (#403) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Add in-depth notes for migration * Apply suggestions from code review Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Implement changes from code review * [TASK] Use bignum formatting * [TASK] Enhances Makefile with a "test-docs" command * [TASK] Tell about Makefile tab indentation oddities * [TASK] Remove "screenshots.json" reference * Update Documentation/WritingDocForExtension/Migrate.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Implement review feedback * [TASK] Use diff syntax instead emphasize-lines * Small adjustments --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .editorconfig | 4 + .../WritingDocForExtension/Migrate.rst | 229 ++++++++++++++++-- .../WritingDocForExtension/_Makefile | 16 ++ .../WritingDocForExtension/_documentation.yml | 17 ++ Makefile | 7 +- 5 files changed, 248 insertions(+), 25 deletions(-) create mode 100644 Documentation/WritingDocForExtension/_Makefile create mode 100644 Documentation/WritingDocForExtension/_documentation.yml diff --git a/.editorconfig b/.editorconfig index eabd4d4c..8866b2f1 100644 --- a/.editorconfig +++ b/.editorconfig @@ -21,3 +21,7 @@ trim_trailing_whitespace = true indent_style = space indent_size = 4 max_line_length = 80 + +[{Makefile,_Makefile}] +# Use tabs for indentation (Makefiles require tabs) +indent_style = tab diff --git a/Documentation/WritingDocForExtension/Migrate.rst b/Documentation/WritingDocForExtension/Migrate.rst index c2d7da1f..53828c69 100644 --- a/Documentation/WritingDocForExtension/Migrate.rst +++ b/Documentation/WritingDocForExtension/Migrate.rst @@ -1,9 +1,9 @@ -.. include:: /Includes.rst.txt -.. index:: - Documentation; Migration - docs.typo3.org -.. _migrate: -.. _register-for-rendering: +.. include:: /Includes.rst.txt +.. index:: + Documentation; Migration + docs.typo3.org +.. _migrate: +.. _register-for-rendering: ============================================= Migration: From Sphinx to PHP-based rendering @@ -15,11 +15,11 @@ Migration: From Sphinx to PHP-based rendering Text rendering to try it out. The new rendering will become mandatory in August 2024. -The main difference that concerns you is that the new PHP-base rendering +The main difference that concerns you is that the PHP-based rendering requires a file called :file:`Documentation/guides.xml` for configuration -while in Sphinx rendering a file called :file:`Docuemtation/Settings.cfg` was +while in Sphinx rendering a file called :file:`Documentation/Settings.cfg` was used. In the transition period we detect if a file called -:file:`Documentation/guides.xml` is present and then switch to the new +:file:`Documentation/guides.xml` is present and then switch to the PHP-based rendering. .. _migrate_guides_xml: @@ -27,20 +27,41 @@ PHP-based rendering. Create the settings file :file:`Documentation/guides.xml` ========================================================= -The Docker container for the new PHP-based rendering additionally contains +The Docker container for the PHP-based rendering additionally contains a migration tool. This tool can be used to automatically create a :file:`Documentation/guides.xml` from the information contained in your :file:`Documentation/Settings.cfg`. -`Docker `__ needs to be installed on your +`Docker `__ (or a drop-in replacement like +`Podman `__) needs to be installed on your operating system for the tool to work: -.. code-block:: shell +.. tabs:: + + .. group-tab:: Docker + + .. code-block:: bash + + docker run --rm --pull always \ + -v $(pwd):/project \ + -it ghcr.io/typo3-documentation/render-guides:latest \ + migrate Documentation + + .. group-tab:: Podman + + .. code-block:: bash + + podman run --rm --pull always \ + -v $(pwd):/project \ + -it ghcr.io/typo3-documentation/render-guides:latest \ + migrate Documentation + + +The last parameter (:bash:`Documentation`) is the name of the directory, where your +:file:`Settings.cfg` is currently placed in. - docker run --rm --pull always \ - -v $(pwd):/project \ - -it ghcr.io/typo3-documentation/render-guides:latest \ - migrate Documentation +After the migration is performed, you will see output about which settings were +converted, if some old settings were discarded, or errors occurred. Try out the rendering locally ============================= @@ -48,16 +69,176 @@ Try out the rendering locally Use our Docker container to render your documentation locally. Read more about :ref:`local rendering `. -Improve your documentation to render without warning -==================================================== +.. _migrate-detailed-steps: + +Further steps to adapt to the PHP-based rendering +================================================= + +You should perform the following tasks to conclude the migration to the +PHP-based rendering tool: + +.. rst-class:: bignums + +#. Improve your documentation to render without warning + + Rendering your documentation should not yield any warnings or errors. + + If you get error messages, often they refer to wrong indentation, missing + :ref:`interlinks `, orphaned files or + outdated ReST identifiers. + + If you are unable to address a warning/error with changes in your documentation + feel free to ask in Slack channel #typo3-documentation (see :ref:`how-to-get-help`). + + If you believe you found a specific bug in the PHP-based rendering, please open + an `issue on GitHub `__. + +#. Remove outdated files + + After the :file:`guides.xml` file has been created, you can remove the old + :file:`Settings.cfg` file. + + You can also delete the :file:`genindex.rst` file which was previously used + to generate an index. + +#. Adapt :file:`Includes.rst.txt` + + The main documentation directory can contain a file :file:`Includes.rst.txt` + to include any fixed text, which will be placed on every page of your rendered + documentation. + + Previously, it was also used to define a list of utilized directives/roles. + + You can either remove that file, or add your fixed text to it. If you remove + the file, remember to also remove all references pointing to that file, like: + + .. code-block:: text + :caption: Documentation/Index.rst + + .. include:: /Includes.rst.txt + + Most official documentation uses this as the stub of the file: + + .. code-block:: text + :caption: Documentation/Includes.rst.txt + + .. You can put central messages to display on all pages here + +#. Remove the entry `genindex` from :file:`Index.rst` (Index/Glossary) + + If you previously had a :file:`genindex.rst` file, this optional index + (or glossary) was rendered as a page through an entry in the file :file:`Index.rst` + like this: + + .. code-block:: diff + :caption: Documentation/Index.rst + + .. toctree:: + :hidden: + + Sitemap + - genindex -If you believe you found a bug in the new PHP-based rendering, please open -an `Issue on GitHub `__. + Remove the entry `genindex` from the list. -Recommended: Activate automatic testing -======================================= + .. hint:: -It is recommended to use an automatic workflow on GitHub Or Gitlab to + See :ref:`migrate-glossary` for details about the future of the + index (glossary) generation. + +#. Avoid code snippets with :file:`.rst` extension + + All files with the extension :file:`.rst` will be interpreted by the PHP-based + rendering, and every file that is just a code snippet placed in an external file + should be renamed to use a :file:`.rst.txt` extension instead. + +Recommendations +=============== + +The following list is not a requirement to utilize the PHP-based rendering, but +follows "best practice" to make the most of your documentation project. + +.. _migrate-to-makefile: + +Add a :file:`Makefile` to your project +-------------------------------------- + +A :file:`Makefile` is a simple command line runner configuration file, which requires +the utility `GNU make `_ +to be available on your Unix-based operating system (Linux, macOS, WSL on Windows, +for example). + +This allows you to perform shortcuts to render your documentation instead +of typing a long :bash:`docker run...` or :bash:`podman run...` command: + +.. code-block:: shell + + make docs + +For inspiration, check out the :file:`Makefile` of the main PHP-based rendering +repository: + +https://github.com/TYPO3-Documentation/render-guides/blob/main/Makefile + +A small example :file:`Makefile`: + +.. literalinclude:: _Makefile + :caption: Makefile + +.. hint:: + + Makefile blocks need to be indented with a TAB character, not spaces. + If your project comes with an :ref:`editorconfig` definition for + code formatting, you should add the following: + + .. code-block:: text + + [Makefile] + # Use tabs for indentation (Makefiles require tabs) + indent_style = tab + + +.. _migrate-to-testing-workflow: + +Activate automatic testing in your project +------------------------------------------ + +It is recommended to use an automatic workflow on GitHub Or GitLab to ensure the extension's documentation renders without warnings. -.. todo: Add a link to the according chapter +An example workflow on GitHub would be established via this file in +:file:`.github/actions/documentation.yml`: + +.. literalinclude:: _documentation.yml + :caption: .github/actions/documentation.yml + + +This creates a workflow entry `Test documentation`, so that on every push to your +repository, and every pull request, the rendering is executed. A commit will then +not be possible, if the rendering fails. The workflow run will be marked with an error, +and shown on pull requests. + +.. _migrate-glossary: + +To be discussed: Index generation (glossary) +============================================ + +The Sphinx rendering allowed to utilize a syntax like the following to +add indexes to your documentation: + +.. code-block:: + :caption: Documentation/Index.rst + + .. index:: + XLIFF; Files + File; XLIFF + +The automatically generated file :file:`genindex.html` would show a +two-column layout of all indexes, with the pages that they were used on. + +The PHP-based rendering does not (yet) support this indexing. + +The current recommendation is to only remove the :file:`genindex.rst` file +from your documentation directory, but keep all the placed `.. index` +directives. If at some point the automatic index generation is re-introduced, +your old indexes will be able to show up again. diff --git a/Documentation/WritingDocForExtension/_Makefile b/Documentation/WritingDocForExtension/_Makefile new file mode 100644 index 00000000..35ecee14 --- /dev/null +++ b/Documentation/WritingDocForExtension/_Makefile @@ -0,0 +1,16 @@ +.PHONY: help +help: ## Displays this list of targets with descriptions + @echo "The following commands are available:\n" + @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' + + +.PHONY: docs +docs: ## Generate projects docs (from "Documentation" directory) + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + + +.PHONY: test-docs +test-docs: ## Test the documentation rendering + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log diff --git a/Documentation/WritingDocForExtension/_documentation.yml b/Documentation/WritingDocForExtension/_documentation.yml new file mode 100644 index 00000000..3076117d --- /dev/null +++ b/Documentation/WritingDocForExtension/_documentation.yml @@ -0,0 +1,17 @@ +name: Test documentation + +on: [ push, pull_request ] + +jobs: + tests: + name: Render documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log diff --git a/Makefile b/Makefile index 325b94fd..35ecee14 100644 --- a/Makefile +++ b/Makefile @@ -7,5 +7,10 @@ help: ## Displays this list of targets with descriptions .PHONY: docs docs: ## Generate projects docs (from "Documentation" directory) mkdir -p Documentation-GENERATED-temp - docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + + +.PHONY: test-docs +test-docs: ## Test the documentation rendering + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log From e47e85f3f8e7fd6471bb64f5d0c41a58ab9f91d5 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Thu, 14 Mar 2024 10:14:37 +0100 Subject: [PATCH 41/45] [TASK] Add note about podman and optimize docker run commands (#402) * [TASK] Add note about podman and optimize docker run commands * [BUGFIX] Revert part of the commit, I think this is still needed. --- Documentation/RenderingDocs/Index.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/RenderingDocs/Index.rst b/Documentation/RenderingDocs/Index.rst index 45e72a26..4d5d69fa 100644 --- a/Documentation/RenderingDocs/Index.rst +++ b/Documentation/RenderingDocs/Index.rst @@ -32,11 +32,18 @@ manual with the following steps: A folder called :file:`Documentation` containing at least the files :file:`Index.rst` and :file:`guides.xml`. -#. Choose your prefered method of rendering (See below): +#. Choose your preferred method of rendering (See below): Make sure that `Docker `__ is installed on your system. -.. tabs:: +.. tip:: + + Did you know: Instead of the :bash:`docker` client you can also use + the lightweight drop-in replacement `Podman `__ to run + the mentioned containers by replacing all :bash:`docker` commands in the + following steps with :bash:`podman`. + +.. tabs:: .. group-tab:: Linux @@ -69,7 +76,7 @@ For your documentation to be published to https://docs.typo3.org, your TYPO3 extension has to have a valid :file:`composer.json` and either a folder called :file:`Documentation` with a :file:`Documentation/Index.rst` and a :file:`Documentation/guides.xml` or a :file:`README.rst` / :file:`README.md` -in the extensions root directory. +in the extension's root directory. The extension has to be publicly available on GitHub or GitLab. You have to establish a :ref:`Webhook ` and the Documentation Team has to From c7de237ba4fefadb85347cfef59796e44c46f461 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 16 Apr 2024 07:53:01 +0200 Subject: [PATCH 42/45] [TASK] Add link to render-guides list of default inventories (#404) --- Documentation/GeneralConventions/GuidesXml.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/GeneralConventions/GuidesXml.rst b/Documentation/GeneralConventions/GuidesXml.rst index 91ca7ab5..c502ee2f 100644 --- a/Documentation/GeneralConventions/GuidesXml.rst +++ b/Documentation/GeneralConventions/GuidesXml.rst @@ -220,6 +220,9 @@ Interlink mapping .. todo: describe interlink mapping more detailed +A list of globally available Interlink (formerly "Intersphinx") repositories +can be found in :ref:`Available default inventories ` + It is possible, though rarely needed to define custom interlink mappings: For example: From 3eb3cfcbf9e342703c359e720e5bf46d4e559366 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 16 Apr 2024 08:29:56 +0200 Subject: [PATCH 43/45] [TASK] Delete Settings.cfg --- Documentation/Settings.cfg | 79 -------------------------------------- 1 file changed, 79 deletions(-) delete mode 100644 Documentation/Settings.cfg diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg deleted file mode 100644 index 4ecdd951..00000000 --- a/Documentation/Settings.cfg +++ /dev/null @@ -1,79 +0,0 @@ -# More information about this file: -# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg - -[general] - -project = Writing Documentation -version = main -release = main -copyright = since 2017 by the TYPO3 contributors - -[html_theme_options] - -# "Edit on GitHub" button -github_repository = TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument -github_branch = main - -# Footer links -project_home = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/ -project_contact = https://typo3.slack.com/archives/C028JEPJL -project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument -project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues -project_discussions = - -use_opensearch = - - -[sphinx_object_types_to_add] -# Some examples for custom configuration schemes -cobj-coa = cobj-coa // cobj-coa // Content object COA -cobj-file = cobj-file // cobj-file // Content object FILE -cobj-text = cobj-text // cobj-text // Content object TEXT - -[intersphinx_mapping] - -# Official TYPO3 manuals -h2document = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/ -# t3content = https://docs.typo3.org/m/typo3/guide-contentandmarketing/main/en-us/ -t3contribute = https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/ -t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ -t3editors = https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/ -# t3extexample = https://docs.typo3.org/m/typo3/guide-example-extension-manual/main/en-us/ -t3home = https://docs.typo3.org/ -t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/ -t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/ -t3tca = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ -# t3translate = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/ -t3tsconfig = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/ -t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/ -# t3ts45 = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/main/en-us/ -# t3viewhelper = https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/ -t3upgrade = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/ - -# TYPO3 system extensions -# ext_adminpanel = https://docs.typo3.org/c/typo3/cms-adminpanel/main/en-us/ -ext_core = https://docs.typo3.org/c/typo3/cms-core/main/en-us/ -# ext_dashboard = https://docs.typo3.org/c/typo3/cms-dashboard/main/en-us/ -# ext_felogin = https://docs.typo3.org/c/typo3/cms-felogin/main/en-us/ -# ext_form = https://docs.typo3.org/c/typo3/cms-form/main/en-us/ -# ext_fsc = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/ -# ext_impexp = https://docs.typo3.org/c/typo3/cms-impexp/main/en-us/ -# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/ -# ext_linkvalidator = https://docs.typo3.org/c/typo3/cms-linkvalidator/main/en-us/ -# ext_lowlevel = https://docs.typo3.org/c/typo3/cms-lowlevel/main/en-us/ -# ext_reactions = https://docs.typo3.org/c/typo3/cms-reactions/main/en-us/ -# ext_recycler = https://docs.typo3.org/c/typo3/cms-recycler/main/en-us/ -# ext_redirects = https://docs.typo3.org/c/typo3/cms-redirects/main/en-us/ -# ext_reports = https://docs.typo3.org/c/typo3/cms-reports/main/en-us/ -# ext_rte_ckeditor = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/ -# ext_scheduler = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/ -# ext_seo = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/ -# ext_workspaces = https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/ - -# External manuals -sphinx = https://www.sphinx-doc.org/en/master/ -t3sphinxtest = https://typo3-documentation.github.io/sphinx_typo3_theme_rendering_test/ - -[extlinks] - -issue = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues/%s | Issue # From 0b6160d4e5664b8d1bdc996e16b05bb9ed465d72 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Tue, 16 Apr 2024 11:21:59 +0200 Subject: [PATCH 44/45] [TASK] Move migration chapter a level up (#405) And advertise it on the front page. --- .../_Makefile | 0 .../_documentation.yml | 0 Documentation/Index.rst | 15 +++++++++++++++ .../Migrate.rst => Migration/Index.rst} | 5 ++--- Documentation/WritingDocForExtension/Index.rst | 5 ++++- 5 files changed, 21 insertions(+), 4 deletions(-) rename Documentation/{WritingDocForExtension => CodeSnippets}/_Makefile (100%) rename Documentation/{WritingDocForExtension => CodeSnippets}/_documentation.yml (100%) rename Documentation/{WritingDocForExtension/Migrate.rst => Migration/Index.rst} (98%) diff --git a/Documentation/WritingDocForExtension/_Makefile b/Documentation/CodeSnippets/_Makefile similarity index 100% rename from Documentation/WritingDocForExtension/_Makefile rename to Documentation/CodeSnippets/_Makefile diff --git a/Documentation/WritingDocForExtension/_documentation.yml b/Documentation/CodeSnippets/_documentation.yml similarity index 100% rename from Documentation/WritingDocForExtension/_documentation.yml rename to Documentation/CodeSnippets/_documentation.yml diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 060e740b..14a7015a 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -31,6 +31,20 @@ reST and Sphinx. ---- +.. container:: row m-0 p-0 + + .. container:: col-md-6 pl-0 pr-3 py-3 m-0 + + .. container:: card px-0 h-100 + + .. rst-class:: card-header h3 + + .. rubric:: :ref:`Migration ` + + .. container:: card-body + + Migrate your documentation to the new, PHP-based reST rendering. + .. container:: row m-0 p-0 .. container:: col-md-6 pl-0 pr-3 py-3 m-0 @@ -113,6 +127,7 @@ What's new in this guide? :hidden: :caption: HOWTOS + Migration/Index WritingDocForExtension/Index WritingDocsOfficial/Index RenderingDocs/Index diff --git a/Documentation/WritingDocForExtension/Migrate.rst b/Documentation/Migration/Index.rst similarity index 98% rename from Documentation/WritingDocForExtension/Migrate.rst rename to Documentation/Migration/Index.rst index 53828c69..3fc22fe5 100644 --- a/Documentation/WritingDocForExtension/Migrate.rst +++ b/Documentation/Migration/Index.rst @@ -3,7 +3,6 @@ Documentation; Migration docs.typo3.org .. _migrate: -.. _register-for-rendering: ============================================= Migration: From Sphinx to PHP-based rendering @@ -182,7 +181,7 @@ https://github.com/TYPO3-Documentation/render-guides/blob/main/Makefile A small example :file:`Makefile`: -.. literalinclude:: _Makefile +.. literalinclude:: /CodeSnippets/_Makefile :caption: Makefile .. hint:: @@ -209,7 +208,7 @@ ensure the extension's documentation renders without warnings. An example workflow on GitHub would be established via this file in :file:`.github/actions/documentation.yml`: -.. literalinclude:: _documentation.yml +.. literalinclude:: /CodeSnippets/_documentation.yml :caption: .github/actions/documentation.yml diff --git a/Documentation/WritingDocForExtension/Index.rst b/Documentation/WritingDocForExtension/Index.rst index 191f81d2..07751a79 100644 --- a/Documentation/WritingDocForExtension/Index.rst +++ b/Documentation/WritingDocForExtension/Index.rst @@ -10,6 +10,10 @@ How to document an extension ============================ +.. hint:: + If your extension does not have a file :file:`EXT:my_extension/Documentation/guides.xml` + you should :ref:`migrate to the new PHP-based rendering `. + This chapter explains how to write documentation for a new extension. This guide uses the `example extension manual `__ @@ -152,7 +156,6 @@ The rendering supports two branches within repositories: :maxdepth: 1 :hidden: - Migrate Webhook ReregisterVersions FAQ From 513054ebb3dfa514ad3daf043c211a7bcd203952 Mon Sep 17 00:00:00 2001 From: Sandra Erbel Date: Tue, 16 Apr 2024 14:06:28 +0200 Subject: [PATCH 45/45] [TASK] Improve wording and add some additions to migration --- Documentation/Images/get_link.png | Bin 0 -> 101647 bytes Documentation/Migration/Index.rst | 165 +++++++++++++++++++++++++++--- 2 files changed, 153 insertions(+), 12 deletions(-) create mode 100644 Documentation/Images/get_link.png diff --git a/Documentation/Images/get_link.png b/Documentation/Images/get_link.png new file mode 100644 index 0000000000000000000000000000000000000000..e91491abae15222e33052b49b88916ab1bb5694d GIT binary patch literal 101647 zcmeEugg+|AOB>8@u=1ef53a*9GdSyd(iWIX)H^7J<|g_;W0*EBshkm$dP&0#8!U zKZavr;b)nNi$9eT7pHw{Z)0p`X@rIK1Qi*DtE4!5>vd=K5?vA#oIi<2jQ`RnWEb|6 z4Q?2OHUf+-Ru>Y$z?&Qp@R5G;bHGc3ONQA2`V==K^r_y8iQUG%#;r7Q<(8iDg!=}% zbZ}(F)5RpwYoBi=A^QSb^!-8r{BE8gRz`!YT|lXT&^`XwArx1^FD?@8;!r93+al-K6A)&$y^^5ZpAFeCZBCoDt-9*|_vcHNA+%#*{v6q;U#d>-YR<<4} z+kLZ?PL_m$fPRdp3G`5qzsasQ=xQ&Y9^HLp2G*1mWeD#jEC>~XvQmdq?um|>mW3385jD6jtRi`3igHtjTm4Z5%3R9pM=&e_As z_c8Pzw7y{3Jx?BD!MRNm_Hac;e&<~Q2OF*J`zuvTr)KgIhse$cJg-O|whD&$Cpub7 zzqq*Ha;<8phyTNBp4z;L>+6mJURHPoqAI#6&M3syT1(2l>`}s36Pc9-=GPJ(_U~!w zb>BY>7eAY~SM4cNh0w1hvhO-4Y7EL$9P|a%uBz0%?`W63z7w_{|8P)5=WATn2O_4m z;Fg2UxK>cq{F?{ksTQc`FFzff-n20jWPmF1^ANkyEzDn)>f}JpQaoyXaivETe@0&v z_x$TST&xeLt8E#l%jvYId`kx6@F+6Lt65$W5@N*}Qw`Lc0f z8`t3vU1FKKD(K6OhoeVJe*d!OTfFCC9V#!Bb%pL=N$64xf$oWt@M49$n4MxY#a^g0 zvLzV9b`j%o#W}7AyIyIo!{xXn2EIWre)Gwdo|n6HieK^dMcLl6%n|yDc0auzfd!%i z72%Iyk%%!py`n_W4-*kLNowsP_)P4MMIg%1rLlM|=%o|~$-oPOsVf|pjT^je$*OM3 zzv!LT>E}PnrW>GMc@^Butf!)1s(YYM zkr$O0KP0xwd&6I`{=-b1oiFbVHe!_*qrn2ND+5*<2&RRnjW*R?p;e^9SJ@jErdu~9 zw@5d&4oMF|F9pRCr=H+3ZsPGF^&7-s*QRgi1#pNd(UL>rQF@JxGw%9)`3bI(htY@f zj~_plY!+iyeN0;@pQbsFY;*c>=|d-@L^uc~p$-dwTM~Zb9a|Xn+ljDmhL;N{_+H0J zO-Sc3>ClNV`Glu_jcF|~ax1Vff*Mg6RT}EF63y-Yh_-K?v;XmZPX60?7)2z@SBkHN zb9~ztbI>21-w(crLZ9BePl8SIoTTIqrE*ykM|ObXqo=z{b9d*V)K9CDd7p?qbG&;W zKdQjj{;hrF19;POf(%P@NO6FB+=v*J;&Y{fXMs<@BQllvbNdv;yRVyCs^g=hox=yj zPaY^3P&-ijOw7CO?NrQrDIpY{73ZO(_jvBOKz*JiWw~ZDW?8D3J$FkEL~uPLKxidZ zDC}h}eW=>Ni10}|*cM<)Jv2{88b((aa`{$j5prjh;;su5!T*ZkA`Zu|uN3XZ6X z>*KED&&LttoIe{Er~ZG(&9 z17~|d+j860HnaKjdAE7F`CQUP)&R9UFR_!C8@Ebs-Mxj&O09NJ{aAfotwgn^_(A@R zy0ZFsDYJ%$T5hp*iMN4)`IpjRlU@^09b)y43NO31mC*E^H2WcX0M@eVR>_HpjU9ilyOReR@tmfL-2FwNJ zG`!KXk-7HW4sGW(pSIHMATYQ8(yUEZpW2|txzv`lGSTkhtGyxGSZiC<&DGSK+;$E$Pk79rB%$J?$m0Z@9Cw3x(t9QRw>l0*hgTn*EwAuhG*d-bvmh-kqm% zr%mUqZ>A(_-Z9*79O1?Op*(x=zI(GltsA@Y+*;;$LgK`r^S`;EbN zYGYbsDuO)PcWsaxZS2#v0WKlzC>nWN`Jph5@WmL__q_LXLHBTM!ac(?!-bh~nQ7z` zWKptaPny!3(-KJT;lJ~9x>2U&aWg{rT6-_OjL+?iaAR_?7Suc#1Y8|UO`Uq+)e zdMgkvR_7y0P7^C3*(^B<+7}iH653J|Cj?;>>f2n~gFgtZcPCU;XfNjy{Q9%LP3X*9V!Zzua(w3HOPHGorsNz%Z+sas-K+LyB^ObH}d>OkL6Q6eqpV-7tV zhAVfQGmd+Y(+}d3;_g}^$sNdBVj!`{u_>_voyQ4QR(9rmJ8zEI{X5MPvjlS;YYwru zVCR0{-jtKJu%p<5wdKnMhbpS}x+6bB4@O^(^5-0DReQIuj6^ycpERv>40ev&R@v<{ z&l>l#R%!&7TG=EX_3sZpq;jSTc3ItcH0e|}+Ebpl1B4M}4fn8X*fc+9SwK^ALV6HLSRo&Q*K+VxY@r(8s&ZU~0dx%Ovz_ z`Kw&-&cm~nr{@maI|Zcb?B@RH*PX$x!DC+Khd;WY-C3yamm)XMhjvC5_m)J)&#Q!P zadGcHJ~iH6d+%~@<3??%+ay2rqw`(yWq(wtU!syQ)lu8w*g4a7>l+k_j-5_x?QI{6 zqxFNcEyLxxPXP?`vND%$&e(biV%ZQf@Y9iFeb<7E+)wE4?Y-LWd0CeDP(d)IJiYzK z3wOilaEWXgtT@pzU8?64ZVBOVJ!`CzlK02i`|$%yimxSVRQD_8o|QhZp*r+$H$AM~ zJ?kWrRW81CL3wfINEG+dGew?hzzmy!a$6%Fi-jI13@Z5$t`jn)7UK(b} zp3;ij*c;JuvvII-&ORX?9FT)&1|e`G2`m#+c-H2(bHol z`t$XlbsD*v{WX)d!+*C0Y>*vO!_LXZ!T#siKvzM`Q~sxBu11z>a5F0aX22Z654ku5 zf42Wu&0jPA(o^-Xo}3RK^8VWOm#TkuRdz747q_tj=5!SP3t#{3{A=ZZI|{O6w*Ct! z{sZTqPXRy+;|sF?i8Nt+A%X9f03IpL;0j8>H$Y`SU%9~FJHQ9?4Sf8LD-jBxu&_k2 zq~Kyou9sHF&E7E%I?cP~QWfhlIlp~k=@+RQNQ+>j6?^-!|Fgyb`hB}mLHFH7xPgx6 zR@3}YzCn9W&vS>luVM3DN#ewz-){VtD9*r#`=zzxRU2L#7StZA`NkLLXYK3bl_wdz z#TXK(yGqL;l^E1jekm@3?RPXm10Zr=jME9IvsA(+;^)aU>B;>KjW2!x@R{J7Rsqxz zNB}hW+Fp{M_%~E+AqiBDs`SR>+uP#(C=8Q930TaN7`n_hy&A&2WVE4Wz&os z2S)qP_q-f1NEIr*8kpG)0`yTBF@yfI5zuWQ3|OHPGBHgYD8~V1F3Gs7{~iveYXD4K z&UyM)8`yI;0l*6uU$}~2|C?0nUNeA`9KMt@QsMi87crw#>!oG>1~x-q0U%l%ZhW!< z_MF88bSlPi@cae6e~f(}55svgpB*0pdu9fpZPM`m)$f+Lg@K1)VrmO8U@ssv_=K`n zZ~q3^*D$bwRkFtu`hufHfijNhFy(LB#rgrOZ=d-#M1)Pp5eSr@DQ#>2W`UM43<)GD z8axL`rxn;$O%Of%?-uBQk!0m(6e}>@EKISVfp*{jk8S=*XO_2t;Yx$D3{3GXr7*=$ zqXv%unzjzX2!IUgF2wC$HvmW;hm}MA_y5L+r5$DjSFFZU@X#Cv;P$vJRlmW;9iZ78 zcmhBL+zbG?W4p8R@BW5d9%IN4TY3V(?a(94aO5h@Z+|l!8HR>kg@?(p>GFnvc5EdV zJtx0u7aaqDHRG943s83jv!P4z@7ewh5@g+dV2} z6W_ZuzX=RTfWh-?X9a%J-yrvlD4=VYrnT=TutE&sjJXO+h5mayn64a#s)(~Q9s$(% z3d00qlwsC?BI~b0ojL}k14u<5fC}6JmMc%#?REYa-bC@*FigSMAg>6JsRIkJ=k>3> zy1!|cO$h9B<%Gij9?a2d51|qm8JrCnzcC6DX1g-JMx_L%O112kS5u@f$M>f*;fQQC61N}JUYwOs zdus2*3}(O4DlRB!X1~ab^eX-y{=}-7>0)@YhPqMuL_zW1d4HkJWQ{Y^f}(;@f8Q5M zyQS19Zul0usKANbd6?ywZRtJ$0Ql~vyY8WgbIo>CulO@nTJW?iaaC!&t zY|#A6Yiy=|Y}mL-DfnWk$mh8-c=5{cO!vW^a-95vESwZH{X~GD&e^g`JE8aHt9hu- zku+3(!s}qX-9qPN1R+XH6Do4<3boZk4nC4tjq_M95AF{I{O8VZRi6FXz`KB71aBXGntyQ|J9+ZEDJYOcj^YGX1iD zTAVb@uGOCpvjhA^1Om|dYA{=t!5(7eecYSKU3>b2eRObLKo!PB*K|)%9~2g-JF~5{ zLG+++dfPZ_bk$0wVpFqEhkVj}!Q>psM6cT%Ph%WjORkSkU%+=|+Z!C$H z2Mqeu!k%U2+uxzFJDno6B&dLUBIjG78cDC7*q`kU@aVB-AqvAf>WoKncAO z5Lpm1RQT9bfNjX|zNYiA5&El5TU(ZD`8Vb)>0yaHL&EiS((i;g?G>SE-V@HFR#raH z=1Q0esQ>iIBa#(FMrP-VdqkJpgxf-~j_c4ttIoMSlu=`8iOi~9=4%4!M$xYZQeFv0 zxUo+5Q3D{T!IU{K*1tc39^jE6?1(r)q6k}v6Q}CFgyT$y1L~m-Q+m za}bK^!=_glD$_`0)6Fc#gqh07qh@+>VF&oihhH=0u-{UATK%@_4Qm zkPv^q{V+_Urxg_f=t@~JK+WBJYdoHcgg|@o;*b>jxO8)`DXdNXf-6>w5N<@J*@leI ziJk@U!-MeR3*Gf*sY~O!-1hoaN@qyx6{-RV{60QrWC`(FHK4IDXh^QHOI^Gn813J%8O`=~;Hx>|fV6NhjHx!IS)UZPS_DyjVQX<&L)VP> zi#E%9QI(_v`p{=~m{qkMS}(#Hr&7^eW;-&BfV< zO=$Jm{%EX4PI($hyCgbVvx9x4Su&PapyX5-l_JbnvszGlUZ5N�|dFbazzKd>vwu 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
@4`ZrvJ4`zSciQGdc&M!>c4#iL%a8U3 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 R^ajNMSxF@c#B(G6{{!plt;YZW literal 0 HcmV?d00001 diff --git a/Documentation/Migration/Index.rst b/Documentation/Migration/Index.rst index 3fc22fe5..3e972a71 100644 --- a/Documentation/Migration/Index.rst +++ b/Documentation/Migration/Index.rst @@ -14,11 +14,11 @@ Migration: From Sphinx to PHP-based rendering Text rendering to try it out. The new rendering will become mandatory in August 2024. -The main difference that concerns you is that the PHP-based rendering -requires a file called :file:`Documentation/guides.xml` for configuration -while in Sphinx rendering a file called :file:`Documentation/Settings.cfg` was -used. In the transition period we detect if a file called -:file:`Documentation/guides.xml` is present and then switch to the +The main difference compared to the Sphinx rendering is that the PHP-based rendering +requires a file called :file:`Documentation/guides.xml` for configuration. +The Sphinx rendering required a file called :file:`Documentation/Settings.cfg`. +In the transition period the process detects if a file called +:file:`Documentation/guides.xml` is present and then automatically switches to the PHP-based rendering. .. _migrate_guides_xml: @@ -26,9 +26,9 @@ PHP-based rendering. Create the settings file :file:`Documentation/guides.xml` ========================================================= -The Docker container for the PHP-based rendering additionally contains +The Docker container for the PHP-based rendering additionally consists out of a migration tool. This tool can be used to automatically create a -:file:`Documentation/guides.xml` from the information contained in your +:file:`Documentation/guides.xml` based on the information contained in your :file:`Documentation/Settings.cfg`. `Docker `__ (or a drop-in replacement like @@ -59,13 +59,25 @@ operating system for the tool to work: The last parameter (:bash:`Documentation`) is the name of the directory, where your :file:`Settings.cfg` is currently placed in. -After the migration is performed, you will see output about which settings were -converted, if some old settings were discarded, or errors occurred. +After the migration is performed, you will see some output in the terminal about which settings were +converted, if some old settings were discarded, or errors occurred. When you see this: + + .. code-block:: text + :caption: Output of the command + + Note: Some of your settings could not be converted: + * html_theme_options + * project_discussions + * use_opensearch + +everything went well. They can be ignored since these files are usually files that +not need to be converted. You now can safely delete :file:`Settings.cfg`. Also delete +file :file:`genindex.rst` in your Documentation directory. Try out the rendering locally ============================= -Use our Docker container to render your documentation locally. Read more about +Use our Docker container to render your documentation locally. Read more about it in :ref:`local rendering `. .. _migrate-detailed-steps: @@ -78,6 +90,20 @@ PHP-based rendering tool: .. rst-class:: bignums +#. Manual modifications of the :file:`guides.yml` + + You have to manually change the following: in the extension tag add the attribute + + .. code-block:: text + :caption: Changes in your :file:`guides.yml` + + interlink-shortcode="vendor/ext_name" + + This you can find in your composer.json under "name". E.g. :json:`friendsoftypo3/jumpurl`. + We recommend to reformulate the code using the mac short cut `cmd + option/alt + l` and to + use for every attribute one line. + + #. Improve your documentation to render without warning Rendering your documentation should not yield any warnings or errors. @@ -174,6 +200,121 @@ of typing a long :bash:`docker run...` or :bash:`podman run...` command: make docs +You should see something like this + +.. code-block:: text + + Successfully placed 7 rendered HTML, SINGLEPAGE, and INTERLINK files into /project/Documentation-GENERATED-temp + +.. _migrate-possible-errors: + +Possible errors using `make docs` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We provide four example errors to guide you through the fixes. + +.. _migrate-interlink-inventory-not-found: + +Interlink inventory not found: HTTP/2 404 +""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: text + + [2024-03-13T12:22:50.661532+00:00] app.WARNING: Interlink inventory not found: HTTP/2 404 + returned for "https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us/objects.inv.json". [] [] + +Here you see that the link `https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us` is not found (404 page). +We can now check via google if there is another link to book Extbasefluid. We found this site `https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/` +We can find the hint: `This manual is no longer being maintained for TYPO3 versions 11.5 and above.`. This tells us that the developers stopped to update the +documentation. We can for example link to the last existing version. Which is 10.4. To do this we have to change the :file:`guides.xml`. Search for the + +.. code-block:: xml + + + +and change `11.5` to `10.4`. Generate files again. + + +.. _migrate-inventory-link-with-key-not-found: + +Inventory link with key ... not found +""""""""""""""""""""""""""""""""""""" + +.. code-block:: text + + [2024-03-13T12:26:40.940930+00:00] app.WARNING: Inventory link with key "h2document:rest-common-pitfalls" + (rest-common-pitfalls) not found. {"rst-file":"GeneratedExtension/Index","type":"ref","targetRef + +We see already that we have to go to file :file:`GeneratedExtension/Index` in the directory "Documentation". +In there we have to delete the line which contains + +.. code-block:: text + + * :ref:`h2document:rest-common-pitfalls` + +.. _migrate-nested-php-domain-components-not-supported: + +Nested PHP domain components (php:class, php:interface, php:enum etc) are not supported +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: text + + [2024-03-25T13:26:11.600367+00:00] app.WARNING: Nested PHP domain components + (php:class, php:interface, php:enum etc) are not supported. + Found php:\Vendor\MyExtension\Interfaces\RequireJsModuleInterface inside + \Vendor\MyExtension\Interfaces\AnotherImportantInterface {"rst-file":"Developer/Index.rst"} [] + +The file :file:`Index.rst` in Documentation/Developer has a wrong indentation. A class must not belong to another class. +Here is the wrong rst code. + +.. code-block:: rst + + .. php:class:: AnotherImportantInterface + + Used for ... + + .. php:class:: RequireJsModuleInterface + + Widgets implementing this interface will add the provided RequireJS modules. + Those modules will be loaded in dashboard view if the widget is added at least once. + +Additionally regarding the name it has to be interfaces and not classes. +`.. php:class:: ExampleInterface` has to be changed to `.. php:interface:: ExampleInterface`. + + +.. _migrate-reference-could-not-be-resolved: + +Reference sitehandling-addinglanguages could not be resolved in LocalizedContent/Index {"rst-file":"LocalizedContent/Index"} [] +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +The next step is to visit the old site, e.g. `https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/LocalizedContent/Index.html`. +There we can search for `sitehandling-addinglanguages` in the rst code by clicking the button "`View Source`". +Finding this: + +.. code-block:: rst + + .. tip:: + For more information on how to add languages and configure their + behaviour in the site configuration, see + :ref:`Adding Languages `. + +We have to click the symbol next to the heading and copy the correct link +which is the one for restructured text. + +.. image:: /Images/get_link.png + :class: with-shadow + :width: 600px + +You have to replace the correct link in e.g. :file:`Documentation/LocalizedContent/Index.rst` to +fix the error. + +.. _migrate-makefile-example-code: + +Makefile example +~~~~~~~~~~~~~~~~ + For inspiration, check out the :file:`Makefile` of the main PHP-based rendering repository: @@ -206,10 +347,10 @@ It is recommended to use an automatic workflow on GitHub Or GitLab to ensure the extension's documentation renders without warnings. An example workflow on GitHub would be established via this file in -:file:`.github/actions/documentation.yml`: +:file:`.github/workflows/documentation.yml`: .. literalinclude:: /CodeSnippets/_documentation.yml - :caption: .github/actions/documentation.yml + :caption: .github/workflows/documentation.yml This creates a workflow entry `Test documentation`, so that on every push to your