diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 9b9a239c..16e686b6 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -190,204 +190,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 in 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..14b323bf --- /dev/null +++ b/Documentation/GeneralConventions/GuidesXml.rst @@ -0,0 +1,197 @@ +.. _guides-xml: + +================================ +:file:`Documentation/guides.xml` +================================ + +This XML file contains meta information and configuration used during rendering +of a manual. + +.. 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 +================== + +Is used for configuration during parsing and rendering. Most available settings +are predefined in the rendering chain supplied by the +:ref:`TYPO3 Rendering Container `. + +.. _settings-guides-project: + +The `` tag +=================== + +This tag can contain the following meta information: + +Project title +------------- + +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. + +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 version of a manual is automatically + +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-guides-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-guides-theme: + +TYPO3 Theme settings +==================== + +Further settings can be made a xml tag +:xml:`` +this tag has to have a reference to the Typo3DocsThemeExtension or it will not +be detected correctly. + +.. _settings-guides-github-workflow: + +Configure the "Edit on GitHub" button +------------------------------------- + +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". + +For example: + +.. code-block:: xml + :caption: Documentation/guides.xml, excerpt + + + + +.. _settings-guides-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". + +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..45bb10d0 --- /dev/null +++ b/Documentation/GeneralConventions/_guides-simple.xml @@ -0,0 +1,21 @@ + + + + + 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` =========================================================