From 77d48e7f84f1e398e4a80001b2dd0fe38c8dc1dd Mon Sep 17 00:00:00 2001 From: Jaapio Date: Mon, 18 Nov 2024 22:48:23 +0100 Subject: [PATCH 1/2] [TASK] Improve markdown support docs With this change we do have better description of the supported markdown features. And some rewording on other parts that were still refering to the sphinx bases rendering. --- .../Basics/GeneralConventions/Format.rst | 26 ++++++++----------- Documentation/Maintainers/Tools.rst | 5 ++-- .../ReStructuredText/Code/Phpdomain.rst | 10 ++++--- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/Documentation/Basics/GeneralConventions/Format.rst b/Documentation/Basics/GeneralConventions/Format.rst index 229f1678..2523bcd5 100644 --- a/Documentation/Basics/GeneralConventions/Format.rst +++ b/Documentation/Basics/GeneralConventions/Format.rst @@ -21,14 +21,14 @@ reST the the Guides, Tutorials, "TYPO3 Explained", Reference, the Changelog and system extensions. -The rendering chain and tools are built and optimized to process reST markup. Please -go ahead and use that format. +The rendering chain and tools are built and optimized to process reST markup. We +recommend using this format for your documentation. As reST is more feature-rich, +and you will benefit from the advanced features of the TYPO3 documentation toolchain. The file ending of reST files is .rst. -The tool `pandoc` can convert existing markdown file into reST format. -Do this once and you are in line with the TYPO3 conventions. - +When you started your documentation in markdown, you can convert it to reST using +our migration tool. .. index:: Documentation; Markdown @@ -38,17 +38,13 @@ Do this once and you are in line with the TYPO3 conventions. Markdown ======== -Currently, you can also use markdown for your (extension) documentation. - -One problem with markdown is that there are many dialects. Since a while there is a standard **commonmark**. -At https://readthedocs.org people are trying to make commonmark available. -See http://blog.readthedocs.com/adding-markdown-support/ for the details. -Without doing lots of investigations we have implemented the same solution for TYPO3 documentation as well. - -This means that our rendering tools detect markdown files as well. They have .md as file ending. - -If you’re encountering problems with the rendering of your markdown files, consider switching to reST. +However we do highly recommend using reST for your documentation, we also support markdown for +your (extension) documentation. The file ending of markdown files is .md. +Our toolchain supports the `commonmark dialect of markdown `__. +This is a standardized version of markdown. We do not support other markdown dialects, although +they might work. We cannot guarantee that they will work in the future. +You can consult our Markdown reference for more information. .. index:: reST; vs. Markdown diff --git a/Documentation/Maintainers/Tools.rst b/Documentation/Maintainers/Tools.rst index 5f71c941..0c9e50cd 100644 --- a/Documentation/Maintainers/Tools.rst +++ b/Documentation/Maintainers/Tools.rst @@ -30,9 +30,8 @@ Generated API per version ------------------------- The content per version https://api.typo3.org/main, https://api.typo3.org/12.4 -etc is generated with Doxygen. A Doxygen Docker image is maintained by the -TYPO3 GmbH in this repository: -https://github.com/TYPO3GmbH/doxygenapi +etc is generated with phpDocumentor. The theme is defined in this repository: +https://github.com/TYPO3-Documentation/render-guides/tree/main/packages/typo3-api The rendering is triggered by this workflow which we in the documentation team can change: diff --git a/Documentation/Reference/ReStructuredText/Code/Phpdomain.rst b/Documentation/Reference/ReStructuredText/Code/Phpdomain.rst index f8c12b30..bdad7bf6 100644 --- a/Documentation/Reference/ReStructuredText/Code/Phpdomain.rst +++ b/Documentation/Reference/ReStructuredText/Code/Phpdomain.rst @@ -7,9 +7,13 @@ PHP domain ========== In order to describe PHP code in TYPO3's documentation, -the Sphinx extension `sphinxcontrib-phpdomain -`__ -is integrated into the rendering process. +our toolchain has an integrated extension inspired by the +`PHP domain`__ +of the Sphinx project. + +The source code of the PHP domain extension is located on GitHub: + +https://github.com/TYPO3-Documentation/guides-php-domain .. _rest-phpdomain-quick-example: From 64ac026e0da146a6a6499ba4a4d4842a7a9494bb Mon Sep 17 00:00:00 2001 From: Jaapio Date: Mon, 18 Nov 2024 22:50:47 +0100 Subject: [PATCH 2/2] [TASK] Improve note about automated migration --- Documentation/Howto/Migration/Index.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/Howto/Migration/Index.rst b/Documentation/Howto/Migration/Index.rst index 96b7eaad..30a384f0 100644 --- a/Documentation/Howto/Migration/Index.rst +++ b/Documentation/Howto/Migration/Index.rst @@ -12,9 +12,12 @@ Migration: From Sphinx to PHP-based rendering .. note:: - 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. + Since November 2024 the official documentation rendering process has been + switched to a PHP-based rendering. When your documentation was configured + with Sphinx, the rendering process will be automatically switched to the + PHP-based rendering. The automatic migration will work for most cases, but + some manual adjustments might be necessary. This guide will help you to + migrate your documentation to the new rendering process. The main difference compared to the Sphinx rendering is that the PHP-based rendering requires a file called :file:`Documentation/guides.xml` for configuration.