Skip to content

Commit

Permalink
[TASK] Move best practises for additonal readme files (#369)
Browse files Browse the repository at this point in the history 
* [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>
  • Loading branch information
@linawolf @brotkrueml
linawolf and brotkrueml authored Jan 23, 2024
1 parent 90b9417 commit c2a2db9
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 113 deletions.
123 changes: 10 additions & 113 deletions Documentation/GeneralConventions/FileStructure.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 <rest-reference>`, 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

#. `<Topic> Guide`, e.g. "Installation and Upgrade Guide",
for collections of articles on a specific topic
#. `<Topic> Reference`, e.g. "TCA Reference",
for a complete encyclopedia
#. `<Topic> Tutorial`, e.g. "Getting Started Tutorial",
for collections of tutorials on a specific topic

and in TYPO3 system and third-party extensions

* `TYPO3 extension <extension-key>`, 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:
Expand Down
95 changes: 95 additions & 0 deletions Documentation/GeneralConventions/ReadmeFile.rst
View file
Original file line number Diff line number Diff line change
@@ -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

#. `<Topic> Guide`, e.g. "Installation and Upgrade Guide",
for collections of articles on a specific topic
#. `<Topic> Reference`, e.g. "TCA Reference",
for a complete encyclopedia
#. `<Topic> Tutorial`, e.g. "Getting Started Tutorial",
for collections of tutorials on a specific topic

and in TYPO3 system and third-party extensions

* `TYPO3 extension <extension-key>`, 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`.

0 comments on commit c2a2db9

Please sign in to comment.