Directories and Files

Directory and File Names

  • All documentation resides in a Documentation subfolder
  • This folder contains the files Settings.cfg, Includes.txt and Index.rst
  • Use CamelCase for file and directory names.
  • reSt files have ending .rst
  • Included files have ending .rst.txt
Documentation/
|
 --> Settings.cfg
|
 --> Includes.txt
|
 --> Index.rst
|
 --> Topic1/
       |
       -> Index.rst
       -> Subtopic1.rst
       -> Subtopic2.rst

If the documentation follows these conventions, the documentation rendering toolchain automatically detects the documentation and renders it correctly on the documentation server.

It is strongly recommended to do it the way it is described here. For alternatives, please look at Additionally Supported Filenames and Formats.

At least the files Settings.cfg, Includes.txt and Index.rst are required in the Documentation folder (at least if you are creating an entire sphinx project and not a single-file solution).

The rest of the files listed here are optional, but strongly recommended.

Settings.cfg

Documentation/Settings.cfg

Important

This file must be adapted for the manual.

It contains some meta information. It also contains start urls for the intersphinx linking mechanism.

The file consists of sections, which start with a keyword in brackets, such as [general]. Make sure that all directives exist in the correct section.

We are showing the contents of this manual's Settings.cfg by using the literalincludes directive.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
# Sphinx setup file for this project
#
# This document lives here:
#    https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# See sample file:
#    https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# Documentation:
#    https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#settings-cfg

[general]

project     = Writing Documentation
version     = 2.0
release     = 2.0.0
t3author    = TYPO3 Documentation Team & community
copyright   = since 1999 by the authors

description = Intended: All you need to know
   to write documentation.


; defaults:
# highlight_language = 'php'
# html_use_smartypants = False
# language = None
# master_doc = 'Index'
# pygments_style = 'sphinx'
# source_suffix = ['.rst', '.md']
# todo_include_todos = False


[notify]

about_new_builds = no


[html_theme_options]

# for theme t3SphinxThemeRtd

# to get the "Edit me on Github Button"
github_branch        = master
github_repository    = TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument


# Fill in values to get links in the "Related Links" section at the lower left
project_contact      = mailto:documentation@typo3.org
project_discussions  =
project_home         = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
project_issues       = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues
project_repository   = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument

# leave this empty
use_opensearch       =


[intersphinx_mapping]

# for cross-referencing across manuals (intersphinx) with :ref:
#
# You must uncomment all manuals you use in your cross-references
#
# Example usage:
#   :ref:`t3contribute:start` will link to start page of Contribution Guide


# t3api         = https://typo3.org/api/typo3cms/
# t3cgl         = https://docs.typo3.org/typo3cms/CodingGuidelinesReference/
t3contribute   = https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/
t3coreapi     = https://docs.typo3.org/typo3cms/CoreApiReference/
t3docteam     = https://docs.typo3.org/typo3cms/Teams/T3DocTeam/
# t3editors     = https://docs.typo3.org/typo3cms/EditorsTutorial/
# t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/
# t3fal         = https://docs.typo3.org/typo3cms/FileAbstractionLayerReference/
# t3inside      = https://docs.typo3.org/typo3cms/InsideTypo3Reference/
t3install     = https://docs.typo3.org/typo3cms/InstallationGuide/
# t3l10n        = https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/
# t3security    = https://docs.typo3.org/typo3cms/SecurityGuide/
# t3services    = https://docs.typo3.org/typo3cms/Typo3ServicesReference/
# t3skinning    = https://docs.typo3.org/typo3cms/SkinningReference/
t3start       = https://docs.typo3.org/typo3cms/GettingStartedTutorial/
t3sitepackage = https://docs.typo3.org/typo3cms/SitePackageTutorial/
t3tca         = https://docs.typo3.org/typo3cms/TCAReference/
# t3templating  = https://docs.typo3.org/typo3cms/TemplatingTutorial/
# t3ts45        = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/
t3tsconfig    = https://docs.typo3.org/typo3cms/TSconfigReference/
t3tsref       = https://docs.typo3.org/typo3cms/TyposcriptReference/
# t3tssyntax    = https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/


[extensions]

# ; Add to list of extensions[] as defined in 'conf.py'.
# ; Mention the extensions you need. Some are loaded automatically
# ; and don't need to be mentioned. Examples:
#

# This is required for embedding YouTube videos

any_name_youtube = sphinxcontrib.youtube

Includes.txt

Documentation/Includes.txt

This file can be the same for all Documentation projects!

Use Includes.txt from this project as an up-to-date example.

We are showing the contents of this manual's Includes.txt by using the literalincludes directive.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
.. This is 'Includes.txt'. It is included at the very top of each and
   every ReST source file in THIS documentation project (= manual).
   
.. This files lives at 
   https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Includes.txt
   Version: 2018-10-16

.. More information about this file:
   https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#includes-txt

.. Define some additional textroles
   See: https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html


.. ---------
.. textroles
.. ---------

.. role:: aspect (emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: rst(code)
.. role:: sep (strong)
.. role:: typoscript(code)

.. role:: ts(typoscript)
   :class: typoscript

.. role:: yaml(code)

.. default-role:: code

.. ---------
.. highlight
.. ---------

.. By default, code blocks are php

.. highlight:: php

Index.rst

Documentation/Index.rst

Important

This file must be adapted for the manual.

It contains text that is displayed on the start page as well as the toctree.

Use Index.rst in this manual as an example.

Minimal Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
   .. include:: Includes.txt

   =================
   T3DocTeam at Work
   =================

   some text


.. toctree::
   :hidden:

   Introduction/Index
   Configuration/Index
  • line 1 : every .rst file should include Includes.txt
  • line 3-5: the header
  • line 10-14: the toctree, which specifically includes the files Introduction/Index.rst, Configuration/Index.rst

Complete Example

We are showing the contents of this manual's Index.rst by using the literalincludes directive.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
.. include:: Includes.txt

.. _start:

=====================
Writing Documentation
=====================

:Writing here:    :ref:`TYPO3 Documentation Team & community <contact-us>`
:Status:          Fully revised (July, 2018)
:License:         `Creative Commons License <https://en.wikipedia.org/wiki/Creative_Commons_license>`__ (CC BY 4.0)



**About this manual:**

   This manual is about writing TYPO3 documentation
   (`docs.typo3.org <https://docs.typo3.org>`__). You can find out about
   how to :ref:`contribute to the documentation <docs-contribute>` and
   :ref:`write extension documentation from scratch <how-to-start-documentation-for-ext>`.

**Find out more in:**

   .. rst-class:: horizbuttons-primary-m

   - :ref:`getting-started`


**Did you know?**

   -  Extension Authors: :ref:`tip-edit-me-on-github`
   -  Extension Authors: :ref:`tip-link-to-issues`
   -  :ref:`tip-of-the-day-2017-02-13`
   -  :ref:`tip-of-the-day-2016-10-08`

   .. rst-class:: horizbuttons-primary-m

   -  :ref:`All tips <Tip-of-the-day>`
   -  :ref:`Tips for extension authors <tips-extension-authors>`

**What's new in this guide?**

   * 2019-02-03 :ref:`news-2019-rest-cheat-sheet`
   * 2019-01-22 :ref:`news-2019-guidelines-for-images`
   * 2018-11-27 :ref:`news-2018-content-styleguide`

   .. rst-class:: horizbuttons-primary-m

   * :ref:`All news <whats-new>`


.. toctree::
   :hidden:

   GettingStarted
   HowToGetHelp
   BasicPrinciples
   GeneralConventions/Index
   WritingReST/Index
   WritingDocForExtension/Index
   WritingDocsOfficial/Index
   RenderingDocs/Index
   Tools/Index
   Appendix/Index
   UsefulLinks
   Sitemap/Index

.editorconfig

.editorconfig

For more information, see .editorconfig.

Use the file in this manual: .editorconfig as an example.

.gitignore

.gitignore

All files listed in .gitignore will be ignored by Git. This is useful for generated files, that should not be added to your repository or for temporary files (e.g. backup files of your editor).

You can ignore additional files by adding them to your .git/info/exclude file.

.gitignore will apply to anyone using the repository, .git/info/exclude is for yourself only and will not be included in the repository on GitHub when you push.

Use the file in this manual: .gitignore as a template.

Minimal Example

# Git global ignore file
# for local exclude patterns please edit .git/info/exclude
# Example file see https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/.gitignore

# ignore generated documentation
*GENERATED*

README.rst

This file will be displayed on GitHub when someone browses through the repositories. Use README.rst from this project as an example! (see source).

The link "Read online" will help people to jump directly to the rendered version.

CONTRIBUTING.rst

This file should contain some information about contributing to the documentation.

You can name it CONTRIBUTING.md or CONTRIBUTING.rst, but as we commonly use reST here, it is best to stick to CONTRIBUTING.rst.

Again, use CONTRIBUTING.rst from this manual.

A link to the file will automatically displayed by GitHub when someone enters the "Issues" area (and has not created an issue yet) or when someone creates an issue.