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. 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. 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. 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 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: 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'. 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. 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: 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). 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:(/).png[(,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.2/_images/landscape.png"] 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 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:

Apache addict I'm involved in several project (OpenWebBeans, Johnzon, Geronimo, Meecrowave, ... - http://home.apache.org/committer-index.html#rmannibucau). Blog: https://rmannibucau.metawerx.net Software engineer @Talend. Components team member. Blog: undx.github.io Technical Writer Frontend Architect R&D Frontend Architect. This is my Talend account. You can check out @jsomsanith for my personal account Senior principal software engineer at @Talend, security contributor at @apache. Blog: http://coheigea.blogspot.com/ QA Automation @ Talend Nantes Committer and PMC member of Apache Beam and Apache Avro. Free education and Open Source enthusiast. Distributed Systems practitioner (victim?) Blog: https://ismaelmejia.com/ Templar I'm a serial tooler. Blog: timeline.antoinenicolas.com Blog: https://www.linkedin.com/in/zoltantakacsdev/ Focused on Big Data technologies. I contribute to open source projects. I'm an Apache Beam committer and PMC member and an Apache Software Foundation member Blog: https://echauchot.blogspot.com/ Senior Cloud Software Architect Product Manager, Information Architect Senior Application Security Engineer Blog: www.talend.com 573PH4N3 D3M15 K3RM480N Senior Software engineer at @komodohealth. Ph.D. in large-scale storage systems. Previous competitive programmer.

If you want to make sure that your component works in Beam and don’t want to use Spark, you can try with the Direct Runner. Check beam.apache.org/contribute/testing/ for more details.