Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TASK] Overhaul general file structure section #361

Merged
merged 5 commits into from
Jan 18, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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`
linawolf marked this conversation as resolved.
Show resolved Hide resolved
* A documentation entry point either for a :ref:`multi page manual <full-documentation>`
linawolf marked this conversation as resolved.
Show resolved Hide resolved
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'.
linawolf marked this conversation as resolved.
Show resolved Hide resolved
* Markdown files have the extension :file:`.md'.
* Included reST files have the extension :file:`.rst.txt'.
linawolf marked this conversation as resolved.
Show resolved Hide resolved
* Use **CamelCase** for directory and file names,
linawolf marked this conversation as resolved.
Show resolved Hide resolved
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