Documenting Apps

Note

The App documentation is part of the packaged App.

Terminology

Index	Item	Description	Origin
1	Title	App title	‘Title’ field in the App. Set during App creation.
2	Company	Company which maintains the App	Company the uploading account belongs to. Set during App creation.
3	App description	App short description	‘Description’ field in the App. Set during App creation.
4	Splash description	Some information about the App, e.g. for advertising it	doc/README.md from the App. See below how to edit it.
5	Link to complete documentation	Complete App documentation	Something referenced from within the doc/README.md. Can be a PDF, a link to some external site, …

App documentation structure

Note

An App (.addon file) is technically a ZIP file. See App file format for details.

• Mandatory contents:

  • doc/README.md — this will be rendered as the product’s splash description ad.

  • Releasenotes.md and Releasenotes.pdf — The Markdown file allows viewing in the App Editor while the PDF file is used in the ZEISS Quality Software Store.

• Recommended contents:

  • Documentation.md (and optional Documentation.pdf) — full App documentation

The App can contain an arbitrary number of additional files in the doc folder referenced from within the files README.md or Documentation.md.

Example

• Documentation related content of the App ‘Python API Examples’:

  

• The README.md is the starting point for rendering the App’s splash description and will reference other files:

  

• This will result in the following splash description:

  

Markdown

Note

See markdown guide for a brief description of the markdown format.

See ZEISS Quality Software Store — FileSelectionAndFiltering for example.

A markdown editor/viewer is integrated in the ZEISS INSPECT App editor.

See Releasenotes template.

Portable Document Format (PDF)

The standard expression to reference a PDF from doc/README.md is:

doc/README.md

See [Documentation](Documentation.pdf) for detailed description.

Converting Markdown files to PDF

The Visual Studio Code extension Markdown PDF allows to convert a Markdown file to PDF.

Link to external documentation

You can create a link to a website providing App documentation by adding a JSON object "documentation": "<url>" to the App’s metainfo.json file:

Example documentation link in metainfo.json

{
    ...
    "documentation": "https://zeissiqs.github.io/zeiss-inspect-addon-api/2025/index.html",
    ...
}

If a documentation link is defined in an App, each dialog window will provide a help button in its title bar.

When the help button is clicked, the user must confirm that the linked documentation pages is openened in the system’s web browser.