Skip to content

Commit

Permalink
[TASK] Overhaul general file structure section
Browse files Browse the repository at this point in the history
  • Loading branch information
linawolf committed Jan 14, 2024
1 parent 7a2710b commit 3a6cf76
Showing 1 changed file with 9 additions and 27 deletions.
36 changes: 9 additions & 27 deletions Documentation/GeneralConventions/FileStructure.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,32 @@ File structure
==============

This page explains the general file structure of a TYPO3 documentation that can
be rendered with the :ref:`rendering toolchain <rendering-docs>`. The toolchain
itself uses a `Sphinx theme <https://typo3-documentation.github.io/sphinx_typo3_theme/>`__
for converting reStructuredText (reST) or Markdown to HTML.
be rendered with the :ref:`rendering toolchain <rendering-docs>`.

.. contents:: Table of Contents:
:backlinks: top
:class: compact-list
:depth: 2
:local:


.. _file-structure-general:

General
=======

In order for the documentation to be rendered, you need at least

#. an index file in one of the following locations in weighted order:

- :file:`Documentation/Index.rst`
- :file:`Documentation/index.rst`
- :file:`Documentation/Index.md`
- :file:`Documentation/index.md`
- :file:`README.rst`
- :file:`README.md`

#. and a theme configuration file under

- :file:`Documentation/Settings.cfg`.
* A valid :file:`composer.json`
* A documentation entry point either for a :ref:`multi page manual <full-documentation>`
or for the rendering of a :ref:`single README file <single-file-documentation>`.

Further conventions are:

* reST files have the extension **.rst**.
* Markdown files have the extension **.md**.
* Included reST files have the extension **.rst.txt**.
* Use **CamelCase** for directory and file names,
for example: Documentation/GeneralConventions/FileStructure.rst.

These conventions pave the way for the *full documentation* and the
*single file documentation* style, the first being preferred for several
reasons.

* reST files have the extension :file:`.rst'.
* Markdown files have the extension :file:`.md'.
* Included reST files have the extension :file:`.rst.txt'.
* Use **CamelCase** for directory and file names,
for example: :file:`Documentation/GeneralConventions/FileStructure.rst`.

.. index:: Full documentation
.. _full-documentation:
Expand Down Expand Up @@ -100,7 +83,6 @@ 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
Expand Down

0 comments on commit 3a6cf76

Please sign in to comment.