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.