ReST Repository Structure
Structure of a repository
We commonly store documentation for 3 usecases:
- in TYPO3 extensions
- in Flow packages and
- in Documentation repositories (e.g. for the TYPO3 Core Documentation)
No matter, which of these usecases you have, the structure of the documentation in all of these the projects always is the same.
The documentation itself always resides in a folder called "Documentation/". Each repository basically contains the same structure. Here it is:
Documentation/ |-- Index.rst |-- Folder1/ ("Folder1" is just an example. The folder can have any name you like) |-- Index.rst |-- Folder2/ (just an example) |-- Subfolder1/ (again an example name) |-- Index.rst |-- Index.rst |-- Images/ |-- Image1.png (just an example) |-- Image2.gif (just an example) |-- ... |-- _make/ .gitignore
The documentation itself always is located in the folder Documentation/. In this folder there must at least be one Index.rst file with your actual text in it. All other files and folders are optional.
When your text becomes longer it makes sense to split it into multiple rst files. E.g. for each chapter you can create a new folder inside "Documentation/" and put an Index.rst file with the text of this chapter in it. Each rst file later will be displayed as one page on typo3.org. The Index.rst in the subfolder then needs to be included in a so called "toctree directive". For more info see Structure of a single reST file.
In your rst files you can also include images: Save the image files inside the folder Documentation/Images/. In your rst file you can then use a so called "replacement text" to include your image. For more information see the syntax for images.
You can render (build) our documentation with a tool called Sphinx. That way it is easy to create the different kinds of output (e.g. HTML files, PDF files...). If you want to try yourself, you will need some tools. The configuration files for Sphinx are already provided in the folder Documentation/_make. If you do not want to build the documentation on your own, just ignore this folder. :-)