CONTRIBUTING.adoc

Contributing to the Eclipse Che Documentation

Table of Contents

• Understanding Che Documentation ecosystem
• Editing and submitting new content
• Building and validating the documentation using Che
• Creating a new topic using Che
• Adding images
• Using special characters
• Building and validating Documentation on a local environment
• Getting support

Understanding Che Documentation ecosystem

• Please read the Code of conduct.

• Eclipse Che documentation project follows a forking workflow. To learn more, read Forking Workflow.

• Eclipse Che documentation follows the IBM Style Guide. If you do not have a paper copy of the styleguide, see the developerWorks editorial style guide on the IBM website. While developerWorks is no longer maintained, it still provides useful reference information.

• To learn more about the tool validating the style, see the vale documentation.

• Eclipse Che documentation uses AsciiDoc for markup. To learn more about AsciiDoc syntax, see the AsciiDoc Writer’s Guide.

• The Eclipse Che documentation project follows guidelines from the Modular Documentation Initiative. As Antora is using the term of module with a different acceptation, this project is refering to them as topics. To understand the nature of topics, see the Appendix A: Modular Documentation Terms and Definitions.

• Eclipse Che documentation uses Antora to build the documentation.

• To learn more about the newdoc tool generating the topic templates, see newdoc documentation.

• To learn more about the test-adoc tool validating the topic files, see the `test-adoc`documentation.

• To learn more about Hosted Che, see the Hosted Che documentation.

Editing and submitting new content

Procedure

1. Open a che-docs workspace running on Hosted Che: https://che.openshift.io/factory?url=https://github.com/<github-handle>/che-docs/tree/<branch-name>/

2. Create a branch <branch-name> for your work.

3. Edit the content.

4. Build and validate the new content. See: Building and validating the documentation using Che.

5. To merge the content, open a pull request. Submit the pull request against the default master branch. Specify as much information as possible in the PR template.

6. To review the pull request: validate the accuracy of content, as well as build, language, links and modular docs requirements. See: Building and validating the documentation using Che.

7. The continuous integration process is publishing content once merged in the master publication branch.

Verification steps

• Navigate to the publication URL of Eclipse Che Documentation: https://www.eclipse.org/che/docs/ and search for your changes.

Building and validating the documentation using Che

To build the Eclipse Che documentation from a Che workspace.

Prerequisites

• Open a Che workspace containing a fork of the documentation. See Editing and submitting new content.

Procedure

1. Open My Workspace.

2. To process generated documentation: Open User Runtimes / bash-curl / Generate reference tables.

3. To build the documentation and start the preview server: open User Runtimes / che-docs-dev / Start preview server.

4. To validate the language of the files currently open, look at the Problems panel in the Bottom Panel. To toggle the view of this panel use the View > Problems menu entry.

5. To validate the compliance of an asciidoc file with Modular Documentation guidelines:

   1. In the Explorer, right-click on file to validate and select Copy Path.

   2. Open User Runtimes / che-docs-dev / Validate Modular Doc.

   3. In the Validate Modular Doc panel in the Bottom Panel, paste the path of the file to validate.

   4. The tool test-adoc tests the file and produces some output.

6. To validate all links: open User Runtimes / linkchecker / Validate links.

Creating a new topic using Che

To create a new topic using a Che workspace:

Procedure

1. Open My Workspace.

2. Open User Runtimes / tools / Create a new topic.

3. Choose the target guide among the available guides:

   • overview: introductory section

   • end-user-guide: documentation for developers: navigating dashboard, working in Che-Theia, and so on

   • installation-guide: installation guides

   • administration-guide: documentation for administrators of the clusters: configuring Che on a cluster, managing users, monitoring resources, security and data recovery

   • contributor-guide: how to develop plug-ins for Che, add new debuggers, languages, and so on

   • extensions: documentation about extensions for Che, such as Eclipse Che4z, OpenShift Connector.

4. Choose the topic nature:

   • assembly

   • concept

   • procedure

   • reference

5. Enter the title for the new topic.

Verification steps

1. The file is generated in the src/main/pages-che-7/<guide_name>/ directory and the script displays related information.

Adding images

Procedure

1. Add images to one of the subdirectories in the src/main/che/docs/images/ directory. Create a new subdirectory if none of the existing ones fits the new image.

2. To publish an image, use the following syntax:

   image::directory/img.png[alt text]

   Images are sized automatically. You can provide a URL to a full-size image, as well as a caption and alt text:

   .Click to view a larger image
   [link=che/docs/images/devel/js_flow.png
   image::devel/js_flow.png[Alt text]

Do not post too many images unless it is absolutely necessary. Animated .gif images are preferred, especially when explaining how to use complex UI features.

Using special characters

• To prevent special characters from being interpreted as formatting mark-up, use pass-through macros.

  Example 1. To escape underscores, asterisks, or backticks, use:

  pass:[VARIABLE_NAME__WITH__UNDERSCORES]

Building and validating Documentation on a local environment

This section describes how to build and validate the documentation on a local environment.

Warning

This is not the preferred method. For the supported method, see: Building and validating the documentation using Che.

Prerequisites:

• A running version of yarn. See Installing Yarn.

• ./node_modules/.bin is in the PATH environment variable.

• A running installation of podman or docker.

• An installation of newdoc.

• An installation of vale.

• An installation of linkchecker.

Procedure

1. Open a shell into the project directory.

2. Install Antora and Gulp using yarn:

   $ yarn

3. To build documentation locally, run:

   $ gulp

4. Navigate to localhost:4000 in your browser.

5. To create a new topic using, run following command:

   $ bash ./tools/newtopic.sh

6. To validate the compliance of an Asciidoc file with Modular Documentation standards, execute following command from a bash terminal, from the root directory of the project:

   $ bash ./tools/test-adoc.sh <PATH_TO_THE_FILE>

7. To validate compliance of a file with the style guide, execute following command in a terminal, from the root directory of the project:

   $ vale <PATH_TO_THE_FILE>"

8. To validate links, execute following command in a terminal, from the root directory of the project:

   $ ./tools/linkchecker.sh

Getting support

GitHub issue

• 

• 

Public Chat

• Join the public eclipse-che Mattermost channel to talk to the community and contributors.