Specify documentation files

Standard layout

The container first makes a copy of your project and then starts documentation rendering. However, because you never know how big projects may become, especially if they include binary files, only the toplevel files and the subfolder ./Documentation/ is copied. This arrangement is called 'standard layout'. Here is an example:

Project
├── Documentation
│   ├── Includes.rst.txt
│   ├── Index.rst
│   ├── Settings.cfg
│   └── …
├── CONTRIBUTE
├── LICENSE
├── LICENSE
├── README.rst
└── …

Nothing special needs to be done if your project adheres to the standard layout. However, to help understanding configuration syntax, here is how the rules for standard layout would be written.

File ./Documentation/Settings.cfg is recommended to hold this settings as this will work locally "at home" and on the build server:

[get_documentation]

# what to keep of the original project "PROJECT" for the documentation
# rendering process "TheProject". Executed in alphabetical order (!)
# of the key names (anyname_* in this example)

anyname_01 = /PROJECT/*                   => /TheProject/
anyname_02 = /PROJECT/Documentation/**/*  => /TheProject/Documentation/

get_documentation is the name of the section. Each following line affects a single file or a group of files if the filename contains a wildcard character '*' or '?'. The double star /**/ means "recursively". So the folder and all its subfolders will be taken into account. Each line is written as 'SOURCE-FILE(S) => DESTINATION-FOLDER' and will trigger a system copy command using rsync. The commands are given in alphabetical order of the keys, no matter in which order you write down the lines.

Custom layout

There may be reasons to spread the documentation source files to other areas of your project. Or, maybe you want to use the .. includeliteral:: directive to directly include your source as code example. Then we have a 'custom layout' and you need to specify which extra files are need.

Examples

Provide all PHP files as well:

[get_documentation]
dummy = /PROJECT/**/*.php => /TheProject

All *.txt, *.md, *.rst text files:

[get_documentation]
dummy1 = /PROJECT/**/*.txt => /TheProject
dummy2 = /PROJECT/**/*.md  => /TheProject
dummy3 = /PROJECT/**/*.rst => /TheProject

Some extra folder trees:

[get_documentation]
dummy1 = /PROJECT/subproject-abc/Documentation/**/* => /TheProject/Documentation/Abc
dummy2 = /PROJECT/subproject-bcd/Documentation/**/* => /TheProject/Documentation/Bcd
dummy3 = /PROJECT/subproject-cde/Documentation/**/* => /TheProject/Documentation/Cde

Only PHP files from Classes:

[get_documentation]
dummy1 = /PROJECT/Classes/**/*.php => /TheProject/Classes

Just a single file:

[get_documentation]
dummy1 = /PROJECT/Configuration/TypoScript/setup.txt => /TheProject/Documentation/_files

If you need something extra AND you know that your whole project isn't too big for the container you can as well include just everything:

[get_documentation]
dummy1 = /PROJECT/**/* => /TheProject

Where to put the configuration

The get_documentation section can go into ./Documentation/Settings.cfg or into ./Documentation/jobfile.json.

Settings.cfg will work locally and on the docs server. And it is easy to maintain.

jobfile.json is more powerful, and, if given, will take precedence. It may be handy to configure everything in just one place if you are the administrator yourself.

jobfile.json is only available to the administrator. So you cannot use jobfile.json to configure server renderings.

For the current container versions v2.3 and v2.4 the crucial part of the jobfile would be written as:

{
   "tctconfig": {
      "get_documentation": {
         "anyname_01": "/PROJECT/* => /TheProject/",
         "anyname_02": "/PROJECT/Documentation/**/*"
      }
   }
}

"tctconfig" is the section that describes how the toolchain should behave.