- Understanding the Che documentation ecosystem
- Project structure, branches and workflows
- The documentation workflow
- Reviewing a documentation pull request
- Editing, submitting and reviewing content
- Creating a page
- Creating a partial
- Adding an example specific to the project context
- Adding an image
- Using special characters
- Building and validating Documentation on a local environment
- Getting support
-
See the Code of conduct.
-
Use the following editorial resources:
-
Minimalism in writing.
-
Style Guide
-
Guidelines from the Modular Documentation Initiative.
TipFor Antora, a module is a collection of content in a component version. This project is referring to Modular Documentation modules as content types. To understand the nature of topics, see the Appendix A: Modular Documentation Terms and Definitions.
-
-
Use the Git Forking Workflow.
-
Eclipse Che hosted by Red Hat is the recommended IDE to edit and build the content.
-
The relevant tools for editing, validation, and publication workflows are available in the
che-docs
container.-
Antora builds the documentation.
-
AsciiDoc is the markup language.
-
htmltest validates the links.
-
Vale validates the language.
-
ShellCheck validates the shell scripts.
-
-
main branch - hosts documentation for next version of Che.
-
release branches (e.g. 7.90.x) - hosts documentations for stable versions of Che.
-
publication branch stores published documents.
-
publication-builder branch hosts a structure and a workflow for publishing documentation to the publication branch.
Che Docs uses GitHub actions workflows for performing CI / release builds, and Pull request check jobs.
CI jobs:
. build-and-validate-on-push.yaml - assemble the project by using the current che-docs:next
image. Triggered on commit to the main branch
. container-build - build quay.io/eclipse/che-docs:next
image.
. https://github.com/eclipse-che/che-docs/blob/main/.github/workflows/call-publication-builder.yml - Triggered on commit to the main or release branch. It will call a workflow from publication-builder branch to publish documentation in publication
branch.
Release jobs: . Release - see Release Eclipse Che documentation.
PR Check jobs:
. Build and validate pull request - assemble the project from the PR branch, using cquay.io/eclipse/che-docs:next
container image.
. Build and verify container - build che-docs
container image.
. Publish Netlify - triggered after build-and-validate-on-pr
completion. Assembled documentation is deployed for preview with "Netlify" platform.
. vale - Vale linting check
. Try in web IDE - view pull request through Eclipse Che. See https://eclipse.dev/che/docs/stable/end-user-guide/try-in-web-ide-github-action/
-
Contributor submits a code pull request in one of the Che repositories with a
status/doc-impact
label. -
The author of the code pull request, or the reviewer ensures the code pull request contains a reference to a documentation pull request for the
main
branch of theche-docs
repository:-
The author of the code pull request, or the reviewer provides a documentation pull request that the members of the documentation team can merge without further editing.
-
Or, the author of the code pull request, or the reviewer provides at least an initial draft of the content and reaches out to the documentation-team members for assistance with editing, to help finalize the documentation pull request.
-
Or, the author of the code pull request, or the reviewer reaches out to the members of the documentation team and work with them on submitting a documentation pull request.
-
-
Merge the code pull request into the
che
repository, for next milestonex.y.z
. -
Merge the documentation content for next milestone
x.y.z
into themain
branch of theche-docs
repository. -
Release
che
milestonex.y.z
.
Review the pull request in the Eclipse Che hosted by Red Hat IDE.
-
Navigate to the pull request
-
Click on the Eclipse Che hosted by Red Hat link in the comments.
-
Build and validate the documentation, and start the preview server: open Menu > Terminal > Run Tasks > che: start-preview-server.
-
In the Terminal panel, watch the output of the che: start-preview-server task to validate the result: internal and external links, language on created and changed files.
-
Navigate to the preview: open Preview.
-
Open created and changed files, and examine the Problems Panel to validate the language. Toggle the view of the Problems Panel using the View > Problems menu entry.
-
Review the pull request. See the code review checklist.
-
A fork of the https://github.com/eclipse/che-docs/ project, accessible at the following URL, where
<organization>
is your GitHub organization or username:https://github.com/<organization>/che-docs/
. See Fork a repository.
-
Open a che-docs workspace running on Eclipse Che hosted by Red Hat:
https://workspaces.openshift.com/#https://github.com/<organization>/che-docs/
. -
Create a branch
<branch-name>
for your work. -
Edit the content.
-
Build and validate the documentation, and start the preview server: open My Workspace > User Runtimes > che-docs > Start preview server.
-
Watch the output of the Start preview server task to validate the result: internal and external links, language on created and changed files.
-
Navigate to the preview: open Preview.
-
Open created and changed files, and examine the Problems Panel to validate the language. Toggle the view of the Problems Panel using the View > Problems menu entry.
-
To merge the content, open a pull request to the default
main
branch. -
When you intend to review a pull request, assign yourself in the GitHub pull request view.
-
Review the pull request. See Reviewing a documentation pull request.
-
The documentation pull request needs a review by the documentation team and by engineering.
-
The continuous integration process is publishing content after the merge in the release branch.
-
Navigate to the publication URL of Eclipse Che Documentation: https://www.eclipse.org/che/docs/ and search for your changes.
Create a page and add it to the navigation when:
-
It is meaningful to have a navigation entry
-
The content might receive cross-references. Avoid cross-references to a page fragment.
-
Define the page destination directory <pages_directory>. It can be:
-
modules/administration-guide/pages/
-
modules/end-user-guide/pages/
-
-
Define the page title, and the page file name: use lower case and separate words with dashes
<title>.adoc
. The directory and the file name determine the page URL. -
Copy one of the templates in the
templates/pages
directory to<pages_directory>/<title>.adoc
. -
Add a cross-reference to the page in the
modules/<guide_name>/nav.adoc
navigation file to create the navigation entry.* xref:<file_name>.adoc[]
-
Verify that an AsciiDoc attribute defines the content type. The page content type can be:
-
Edit the Antora metadata in the file.
Example 1. Template metadata for a page:description: A description of the page stored in an HTML meta tag. :keywords: comma-separated values, stored, in an HTML, meta, tag :navtitle: Title :page-aliases: [id="title"] = Title
-
Author the content.
Create a partial and add it to an assembly page when:
-
The content is a concept, procedure or reference to include in a page.
-
The content might not receive cross-references.
-
Copy one of the templates in the
templates/partials
directory tomodules/<guide_name>/partials/<lowercase_title>.adoc
. -
Verify that an AsciiDoc attribute defines the content type. The partial content type can be:
-
Add an include statement in the corresponding page in
modules/<guide_name>/pages/
:include::partial$<file_name>.adoc[leveloffset=+1]
-
Edit the metadata in the file.
[id="title"] = Title
-
Author the content.
Create an example specific to the project context when:
-
Upstream and downstream require a different content.
-
The content is a block of text.
-
Using an AsciiDoc attribute is not an option.
The include statement contains the project-context
attribute to ensure upstream and downstream use a different file.
These snippets have no content type.
-
Create the file
modules/<guide_name>/examples/snip_che_<lowercase_title>.adoc
, and author the content. -
Add an include statement in the corresponding page
templates
directory tomodules/<guide_name>/pages/<title>.adoc
.include::example$snip_{project-context}<file_name>.adoc[leveloffset=+1]
-
Author the content.
Avoid using images unless necessary.
-
Add the image to the
modules/__<guide_name>__/images/
directory corresponding to the guide including the image. -
To publish a block image, use the following syntax. See Antora documentation - Add block images and Asciidoctor documentation - Images.
Example 2. Block image.__<Image caption>__ image::__<image_name>__.png[__<Image title>__]
-
The publication tool resizes images. To provide a link to a full-size image, add a
link
attribute:Example 3. Block image with a link to the full-size image.__<Image caption>__ image::__<image_file_name>__[__<Image title>__,link="../_images/__<image_file_name>__"]
-
To exclude special characters from markup substitutions, use the inline
pass
macro.Example 4. Displaying a variable name containing underscorespass:a,c,m[VARIABLE_NAME__WITH__UNDERSCORES]
- Result
-
VARIABLE_NAME__WITH__UNDERSCORES
This section describes how to build and validate the documentation on a local environment using the che-docs
container.
Warning
|
This is not the preferred method. For the supported method, see: Editing, submitting and reviewing content. |
-
Open a shell prompt into the project directory, and build and validate the documentation using and instance of the
che-docs
container.$ ./tools/runnerpreview.sh
-
Read the output for the results of the links and language validation steps.
-
Navigate to
localhost:4000
in your browser.
-
Join the public eclipse-che Mattermost channel to talk to the community and contributors.