How to explicitly specify tables of contents (Directory-based EHANDBOOK Container-Build)
This how-to guide applies to the Directory-based EHANDBOOK Container-Build approach. For ASAM-based EHANDBOOK Container-Build approach, refer to the ASAM CCX specification and the usage of ABLOCKs for TOCs in particular. |
The approach described in this how-to guide for Directory-based EHANDBOOK Container-Build approach can also be applied when generating EHANDBOOK Containers for ASCET-DEVELOPER apps. |
Background
Each EHANDBOOK Container comes with one or multiple tables of contents. A table of contents provides a high-level navigation structure for the textual contents of an EHANDBOOK Container. In EHANDBOOK-NAVIGATOR, the contents of a table of contents is shown in the Document Explorer.
EHANDBOOK supports to specify multiple tables of contents such that different users of the ECU software documentation can use different navigation structures. In EHANDBOOK-NAVIGATOR, users can switch between the provided tables of contents. Through this, they can choose a navigation structure depending on their use case or personal preference.
How tables of contents are derived by default
The directory-based EHANDBOOK Conainer-Build tool-chain has a built-in feature to automatically derive two standard tables of contents:
-
Alphabetically list of functions: This is a flat list of ECU functions or software components in alphabetic order
-
Software architecture view: This is a hierarchical structure that mimics the ECU software architecture as specified by the directory structure
Benefits are:
-
No effort to specify a table of contents at all
-
Standard tables of contents are created automatically
How tables of contents can be specified explicitly
Starting with EHANDBOOK 10.2, it is possible to specify the tables of contents explicitly. Through this, the automatically generated tables of contents can be replaced with customized ones.
The format of the configuration file is YAML.
tocs.yaml - a YAML file to specify table of contents
To specify the structure of the tables of contents, a configuration file with the name tocs.yaml
has to be provided in the root directory that is passed to EHANDBOOK Container-Build.
└── 📒 ECU_SW_XYZ (1)
└── 📒 SWC_1
├── 📒 SWC_2
.
.
.
├── 📒 SWC_n
├── 📒 Composition_1
├── 📒 Composition_2
└── 📄 tocs.yaml (2)
1 | Root input directory to be passed to EHANDBOOK Container-Build |
2 | File with explicit specification of tables of contents |
For ASCET-DEVELOPER, the Figure 4. Placement of
tocs.yaml for ASCET-DEVELOPER apps |
Syntax of tocs.yaml
The following listing shows an example for the syntax of the YAML file. You can download the file from here.
docuUnits: (1)
- id: SWC_1 (2)
displayName: "Software Component 1" (3)
- id: SWC_2
displayName: "Software Component 2"
- id: SWC_n
displayName: "Software Component n"
- id: Composition_1
displayName: "Composition 1"
- id: Composition_2
displayName: "Composition 2"
tocs: (4)
- displayName: Alphabetic list of software components (5)
contents: (6)
- idRef: SWC_1 (7)
- idRef: SWC_2
- idRef: SWC_n
- displayName: Software architecture
contents:
- idRef: Composition_1
contents: (8)
- idRef: SWC_1
- idRef: SWC_2
- idRef: Composition_2
contents:
- idRef: SWC_n
1 | docuUnits: List of documentation untis from which tables of contents can be specified. |
2 | id: Identifier of the documentation unit. This complies to the name of the directory that represents the software component, composition or any other documentation chapter. |
3 | displayName: The human-readable name that shall be displayed in the table of contents. |
4 | tocs: Start of YAML section where the tables of contents for the EHANDBOOK Container are specified. |
5 | displayName: The human-readable name that shall be displayed for a table of contents. |
6 | contents: Start of YAML section where entries for the tables of contents are specified. |
7 | idRef: Reference to a documentation unit. |
8 | contents: Nested YAML section with entries for sub-chapters. Useful for creating navigation hierarchies, e.g. to resemble the software architecture of an ECU. |
Custom tables of contents in EHANDBOOK-NAVIGATOR
The following screenshot shows the Document Explorer after the generated EHANDBOOK Container is loaded in EHANDBOOK-NAVIGATOR. The first tables of contents - Alphabetic list of software components - is shown.
Using the select button, users can explore and switch to another table of contents.
This is how the Software architecture looks like.
Benefits
-
Define an arbitrary set of tables of contents (one or multiple)
-
Provide a custom order of the tables of contents (first table of contents will be shown when the EHANDBOOK Container is opened)
-
Provide custom names for the entries in the tables of contents
-
Provide custom ordering of entries in the tables of contents