From 9e64290a95f6b73ca2960c56a629b1e00630f3b8 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Sun, 14 Jan 2024 13:03:25 +0100 Subject: [PATCH 1/8] [TASK] Overhaul Startpage and menu / toctree configuration --- .../GeneralConventions/FileStructure.rst | 182 +++++------------- 1 file changed, 53 insertions(+), 129 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 84c3cd88..0f9ee42e 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -71,41 +71,13 @@ 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 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 document title. This way you can link to a documents start page by: @@ -114,70 +86,31 @@ document title. This way you can link to a documents start page by: See :ref:`TYPO3 Explained `. +If your manual has more pages then this one it must contain a table of content +directive called :rst:`.. toctree::`. The `toctree` on the start page +defines which pages will be displayed in the menu on the left 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 startpage can be hidden, it then only influences the menu +on the left: +.. 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 menu on the left. -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` directives on the start page. +Each `toctree` should have a :rst:`:caption:` in this case. -or - if it has the subpage "Sell Widget" - at +The menu on the left 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 6be6c7c0055eb7fa1ecc4374843b37238adce047 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Wed, 24 Jan 2024 16:28:31 +0100 Subject: [PATCH 2/8] [TASK] Apply suggestions from code review --- Documentation/GeneralConventions/FileStructure.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 0f9ee42e..bf006176 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -88,7 +88,7 @@ document title. This way you can link to a documents start page by: If your manual has more pages then this one it must contain a table of content directive called :rst:`.. toctree::`. The `toctree` on the start page -defines which pages will be displayed in the menu on the left of the rendered +defines which pages will be displayed in main navigation of the rendered manual. .. _index-rst-table-of-contents: @@ -96,8 +96,8 @@ manual. Configure the menu - the toctree ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `toctree` on the startpage can be hidden, it then only influences the menu -on the left: +The `toctree` on the startpage can be hidden, it then only influences the main +navigation: .. code-block:: rst @@ -126,15 +126,15 @@ Or it can be inserted visibly into the start page to provide an entry point: 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 menu on the left. +limit the level of pages displayed in the main navigation. For more information on possible options on the `toctree` directive see chapter :ref:`Toctrees in the reST reference `. -It is possible to use more then one `toctree` directives on the start page. +It is possible to use more then one `toctree` directive on the start page. Each `toctree` should have a :rst:`:caption:` in this case. -The menu on the left will then be divided into sections labeled by those +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: From f181cce1fbd63103063c2eaa3987f855f518b1fe Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Thu, 25 Jan 2024 08:05:51 +0100 Subject: [PATCH 3/8] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/GeneralConventions/FileStructure.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index bf006176..e6ce2062 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -79,14 +79,14 @@ 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. -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 one it must contain a table of content +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. @@ -96,7 +96,7 @@ manual. Configure the menu - the toctree ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `toctree` on the startpage can be hidden, it then only influences the main +The `toctree` on the start page can be hidden, it then only influences the main navigation: .. code-block:: rst From 8e73b9c0859144fe8dc890be4b78aa9d59104d42 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Thu, 25 Jan 2024 08:06:14 +0100 Subject: [PATCH 4/8] Update Documentation/GeneralConventions/FileStructure.rst --- Documentation/GeneralConventions/FileStructure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index e6ce2062..e15323c9 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -143,7 +143,7 @@ that: .. toctree:: :hidden: - :caption: BASICS + :caption: Basics About HowToGetHelp From d1ded680f43bceb35d39ea46f8a08b1c219c1d7f Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Thu, 25 Jan 2024 08:07:37 +0100 Subject: [PATCH 5/8] Update Documentation/GeneralConventions/FileStructure.rst --- Documentation/GeneralConventions/FileStructure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index e15323c9..bc9af465 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -74,7 +74,7 @@ displayed on GitHub and GitLab. 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. From 9bf22e4ef5f9f7582099ea227ee2af24bb2142fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Fri, 26 Jan 2024 10:13:51 +0100 Subject: [PATCH 6/8] Update Documentation/GeneralConventions/FileStructure.rst --- Documentation/GeneralConventions/FileStructure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index bc9af465..5248410d 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -151,7 +151,7 @@ that: .. toctree:: :hidden: - :caption: HOWTOS + :caption: Howtos WritingContent/Index WritingDocForExtension/Index From c454cfcc6fd0a227b5f0e8b44b9f521757cc7980 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Fri, 26 Jan 2024 10:14:06 +0100 Subject: [PATCH 7/8] Update Documentation/GeneralConventions/FileStructure.rst --- Documentation/GeneralConventions/FileStructure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 5248410d..38cec4d1 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -159,7 +159,7 @@ that: .. toctree:: :hidden: - :caption: ADVANCED + :caption: Advanced HowToAddTranslation/Index GeneralConventions/HowToUpdateDocs From 358f381772da6c0c03ccd027247f60715bcf54cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Fri, 26 Jan 2024 10:14:21 +0100 Subject: [PATCH 8/8] Update Documentation/GeneralConventions/FileStructure.rst --- Documentation/GeneralConventions/FileStructure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 38cec4d1..8a3f85c0 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -167,7 +167,7 @@ that: .. toctree:: :hidden: - :caption: MAINTAINERS + :caption: Maintainers Maintainers/Index