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] [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`.