Note
This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.
If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.
Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.
File structure¶
This page explains the general file structure of a TYPO3 documentation that can be rendered with the rendering toolchain.
Table of Contents:
General¶
In order for the documentation to be rendered, you need at least
- A valid composer.json
- A documentation entry point either for a multi-page manual or for the rendering of a single README file.
The following rules are mandatory or your documentation will not render:
- reST files MUST have the extension :file:`.rst'.
- Markdown files MUST have the extension :file:`.md'.
Further conventions are:
- Included reST files SHOULD have the extension :file:`.rst.txt'.
- Use CamelCase for directory and file names,
for example:
Documentation/GeneralConventions/FileStructure.rst
. - Each directory SHOULD have a file named
Index.rst
it is used as fallback if a page is not found during switching versions.
Full documentation¶
To render a complete documentation manual you need a folder called
Documentation
with at least a reStructured Text file as entry point named
DocumentationIndex.rst
and a configuration file called
Documentationguides.xml
. Add more files as needed.
You can keep a README.md
or 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.
.
├── composer.json
├── README.rst
└── Documentation
├── guides.xml
├── Index.rst
├── Sitemap.rst
└── ..
Start page: Documentation/Index.rst
¶
The documentation start page (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.
The start page should contain an anchor target .. _start:
above its
document title. This way you can link to a documents start page by:
See :ref:`TYPO3 Explained <t3coreapi:start>`.
If your manual has more pages then this start page it must contain a table of content
directive called .. toctree::
. The toctree
on the start page
defines which pages will be displayed in main navigation of the rendered
manual.
Optional: Documentation/Sitemap.rst
¶
The Sitemap.rst
contains the sitemap of the documentation.
It is an almost empty file that is automatically filled during rendering.
:template: sitemap.html
.. include:: /Includes.rst.txt
=======
Sitemap
=======
.. The sitemap.html template will insert here the page tree automatically.
Settings: Documentation/guides.xml
¶
This file contains the metadata and configuration for the rendering with the TYPO3 theme.
Read more about the Configuration of the rendering - guides.xml.
Hint
If you are migrating from the legacy Sphinx-based rendering and still have
a Documentation/Settings.cfg
you can use an automatic migration
tool to migrate the settings.cfg into a guides.xml.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
links-are-relative="true"
default-code-language="php"
>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
project-home="https://extensions.typo3.org/extension/news/"
project-contact="https://typo3.slack.com/archives/C03TG7QJT"
project-repository="https://github.com/georgringer/news"
project-issues="https://github.com/georgringer/news/issues"
edit-on-github-branch="main"
edit-on-github="georgringer/news"
typo3-core-preferred="11.5"
interlink-shortcode="georgringer/news"
/>
<project title="News system" release="main (development)" version="main (development)"
copyright="since 2010 by Georg Ringer & Contributors"/>
<inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>
Single file documentation (README)¶
For third-party TYPO3 extensions that do not require extended documentation
you can also publish a README.rst
or README.md
to
https://docs.typo3.org/
For this workflow the README(.rst/.md)
MUST be situated in the
extension's root folder. The :file:`Documentation/' folder can then be omitted.
README.rst
¶
For single file documentation, the README.rst
contains the entire
documentation.
This should also contain links to all aspects of the project to guide the reader to the next steps, for example
<badges>
=========
<project>
=========
<abstract>
Installation
============
..
Configuration
=============
..
Usage
======
..
.. csv-table::
:header: "", "URL"
**Repository:**, :samp:`https://{<vcs-repository>}`
**Read online:**, :samp:`https://docs.typo3.org/p/{<package-name>}/main/en-us/`
**TER:**, :samp:`https://extensions.typo3.org/extension/{<extension-key>}/`
<badges>
# <project>
<abstract>
| | URL |
|------------------|---------------------------------------------------------------|
| **Repository:** | https://<vcs-repository> |
| **Read online:** | https://docs.typo3.org/p/<package-name>/main/en-us/ |
| **TER:** | https://extensions.typo3.org/extension/<extension-key>/ |