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.

Figure 1. Document Explorer of EHANDBOOK-NAVIGATOR, showing a table of contents

Figure 2. Button to switch to other tables of contents

Figure 3. Select a table of contents to be shown

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 tocs.yaml file must be placed in the same directory as the .app file for which an EHANDBOOK Container shall be generated.

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.

Figure 5. Document Explorer of EHANDBOOK-NAVIGATOR, showing custom table of contents for "Alphabetic list of software components"

Using the select button, users can explore and switch to another table of contents.

Figure 6. Document Explorer of EHANDBOOK-NAVIGATOR, showing selection between available tables of contents

This is how the Software architecture looks like.

Figure 7. Document Explorer of EHANDBOOK-NAVIGATOR, showing custom table of contents for "Software architecture"

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