Talend Component Kit Developer Reference Guide :: Contributing to Talend Component Kit documentation

This document explains how Asciidoctor is used in the context of Talend Component Kit as well as the specific processes in place.

For general guidelines about Asciidoctor, refer to the Asciidoc Syntax quick reference page.

How to contribute

There are two ways to suggest modifications or new content. Both of the options below require you to have a GitHub account created.

On every page of the Talend Component Kit Developer Guide, a Suggest and edit button is available. It allows you to access the corresponding source file on GitHub and to create a pull request with the suggested edits. The pull request is then assessed by the team in charge of the project.
Fork the Runtime repository of the Talend Component Kit project and edit .adoc files located under documentation\src\main\antora\modules\ROOT\pages. Make sure to follow the guidelines outlined in the current document, especially for large modifications or new content, to make sure it can properly be rendered. When done, create a pull request that will be assessed by the team in charge of the project.

General organization guidelines

The documentation is made of:

Documentation files manually written under documentation\src\main\antora\modules\ROOT\pages.
Documentation files automatically generated from the source code under documentation\src\main\antora\modules\ROOT\pages\_partials. These files are individually called in manually written files through includes.
Assets, especially images, stored in the documentation\src\main\antora\modules\ROOT\assets folder. Some subfolders exist to categorize the assets.

Each file has a unique name and is rendered as a unique HTML page. Some of the files are prefixed to help identifying the type of content it contains. Most common examples are:

index- for pages referenced from the main index page. These pages also contain specific attributes to be correctly rendered on the main index page (see 'List of metadata attributes' below).
tutorial- for tutorials/guided examples.
generated_ for pages generated from the source code. These pages are generally stored in the _partials folder.

List of metadata attributes

For all pages:

:page-partial indicates that the current .adoc file can be included in another document using an include::. This attribute has no value.
:page-talend_skipindexation: indicates that the current .adoc file must not be indexed. This attribute has no value. Add it to files that should not be returned in the search, like index files that only contain includes.
:description: is the meta description of the file. Each .adoc file is rendered as an HTML file.
:keywords: is the list of meta keywords relevant for the current .adoc file. Separate keywords using simple commas.
:page-talend_stage: draft indicates that the current document is a draft and is not final even if published. It triggers the display of a small banner indicating the status of the page. Remove this attribute once the page is final.

For pages that should appear as a tile on the index page:

:page-documentationindex-index: is the weight of the page. A low weight indicates that the page should be one of the first tiles to appear. A high weight will push the tile towards the end of the list in the index page.
:page-documentationindex-label: is the title of the tile in the index page.
:page-documentationindex-icon: is the icon of the tile in the index page. The value of this attribute should be the name of a free icon on fontawesome.
:page-documentationindex-description: is a short description of the page that will be displayed in the tile under its title.

For pages containing API descriptions:

:page-talend_swaggerui: true indicates that the page contains some API reference that should be displayed using Swagger UI

Conditionality regarding output formats

The Talend Component Kit documentation is published as HTML and PDF. Some parts can differ between these two versions, such as lists of links, that are not functional in the PDF version.

To avoid this, it is possible to define some conditionality to have some content only displaying in one of the output formats only. For example:

ifeval::["{backend}" == "html5"]
[role="relatedlinks"]
== Related articles
- xref:tutorial-generate-project-using-starter.adoc[Generating a project using the starter]
- xref:component-configuration.adoc[Defining component layout and configuration]
- xref:tutorial-configuration-sensitive-data.adoc[Masking sensitive data]
- xref:best-practices.adoc[Best practices]
endif::[]

Content

Page and section levels

Every .adoc file can only contain one 'level 1' title (=). It is the title of the page and is located at the top of the document. It is a best practices that all sublevels added to the document are kept consistent. For example, don’t use a 'level 3' (===) section directly inside a 'level 1'.

= Document title
  == Section 1 title
    === Section 2 title
    === Section 2 title
      ==== Section 3 title
      ==== Section 3 title
  == Section 1 title
  == Section 1 title

When possible, avoid going lower than section 2 (===) to keep the page readable. In the HTML output, the document title is renderedh1, section 1 titles as h2, etc. The "in-page" navigation available on the right side of the HTML rendering only considers h2 and h3 elements. Other levels are ignored to keep the navigation readable and simple.

Reusing content with includes

It is possible to reuse content through "includes". Includes can be used to reuse entire files in other files, allowing to avoid copy pasting.

When using an 'include' (calling an .adoc file from another .adoc file), you can specify a level offset to keep the hierarchy consistent in the current document. Avoid using includes if not absolutely necessary. An include can be done as follows:

= Document title

include::doc1.adoc[leveloffset=+1]

include::doc2.adoc[leveloffset=+1]

In this case, both doc1.adoc and doc2.adoc are rendered in the same page and their content is offset by one level, meaning that the document title of doc1 becomes a section 1 title (h2) instead of an h1 in the final rendering, and so on.

Note that both doc1.adoc and doc2.adoc will in addition be rendered as standalone pages (doc1.html and doc2.html).

Adding images

All images are stored under documentation > src > main > antora > modules > ROOT > assets > images. Relatively to .adoc files, it can be ../assets/images/ or ../../assets/images for _partials (automatically generated from code) pages. To avoid handling different relative paths, the backend already resolves directly image: to the image folder. Hence, paths to images should start with the following:

image:(<subfolder>/)<image_name>.png[<image_name>(,parameters)]

If there is no subfolder, type the image name right away. Adding an image title is mandatory to avoid empty broken spaces in the content. If necessary, you can add more parameters separated by a comma between the same brackets as the image title, such as the desired width, height, etc.

Use values in % for image size. For example; image:landscape.png[Landscape,70%,window="_blank",link="https://talend.github.io/component-runtime/main/1.51.1/_images/landscape.png"]

Tables

In a general manner, avoid using tables if there are other solutions available. This is especially the case for complex tables that include assets or big code samples, as these can lead to display issues.

Table example: value

API	Type	Description
@o.t.s.c.api.service.completion.DynamicValues	dynamic_values	Mark a method as being useful to fill potential values of a string option for a property denoted by its value.
@o.t.s.c.api.service.healthcheck.HealthCheck	healthcheck	This class marks an action doing a connection test

Admonition blocks

The following elements can be used to create admonition blocks. However, avoid using them one after another as it can make reading more difficult:

NOTE: for a simple information note
IMPORTANT: for a warning. Warnings should include information that lead to important errors if not taken into account
TIP: for alternative ways or shortcuts to ease a process or procedure

Admonition blocks should be kept as simple and short as possible. In some niche cases, it may be required to insert more complex content in an admonition block, such as a bullet list. In these cases, they should be formatted as follows:

[IMPORTANT]
====
The model allows you to define meta information without restrictions. However, it is highly recommended to ensure that:

- a datastore is used in each dataset.
- each dataset has a corresponding source (mapper or emitter) which has a configuration that is usable if the software only fills the dataset part. All other properties must not be required.
====

Sample page

= Page title
:description: This is a sample Asciidoctor page
:keywords: Ascii, asciidoc, sample, documentation
:attribute1:
:attribute2:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

== Section 1 title

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

=== Section 2 title

Some *bold* or _italic_ or `command` to highlight specific parts of the content

.Some code block
[source]
\\ remove the extra '\' characters
\----
some code
for my
code codeblock
    with indentation
    if needed
\----

=== Section 2 title

image:my_image.png[The image,window="_blank",link="https://talend.github.io/component-runtime/main/{page-component-version}/_images/my_image.png",300]

.Table title for a table with 2 columns that contain images
[cols="1a,1a",role="table gallery table-striped",options="header,autowidth"]
|===
|Studio Rendering | Web Rendering

|image::gallery/widgets/studio/list.png[Studio List,100%,window="_blank",link="https://talend.github.io/component-runtime/main/{page-component-version}/_images/gallery/widgets/studio/list.png"]
|image::gallery/widgets/web/list.png[Web List,100%,window="_blank",link="https://talend.github.io/component-runtime/main/{page-component-version}/_images/gallery/widgets/web/list.png"]
|===

== Section 1 title

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

[role="relatedlinks"]
== Section 1 title only displaying in HTML
- xref:file1.adoc[Xref1 only displaying in HTML]
- xref:file2.adoc[Xref2 only displaying in HTML]