Overview

Ignite documentation sources are stored in the main Ignite repository together with the rest of the Ignite source code. The docs are written in the AsciiDoc format and transformed into the HTML form with the Jekyll toolchain. The published HTML version of the docs, that is accessible under the URL https://ignite.apache.org/docs/, is stored in the Ignite Website repository. The picture below explicates on how the things are tethered together:

The sections below cover the code contribution and publication processes in detail. 

Contributing to Documentation

The documentation contribution process adheres to the main contribution process with several minor adjustments when it comes to the minor edits, fixing typos, or doing little corrections. For instance, while you always need to create a JIRA ticket for significant documentation changes and follow the main contribution process, with minor changes (such as typos correction) a committer can take a shortcut and commit a change to the repo without the need of having a respective JIRA ticket. 

Contributing Significant Changes

Under significant changes, we assume new features, notable rework on an existing documentation page, any other changes that require review by community members. Follow this process to contribute a significant documentation change:

1. Clone the main Ignite repository and get to know our development process. You can fork the repository or have a clone of the main repository on your local machine.
2. Make sure a JIRA ticket is created for the change and the component property is set to documentation.

3. Find documentation sources under the ignite_root/docs/_docs directory and do necessary modifications:

   • Refer to the How to Contribute section of the documentation module to understand the syntax of the AsciiDoc format and the rest of the files located under the _docs directory.
   • Update the ignite_root/docs/_docs/toc.yaml file if you add a new documentation page.
   • Every new documentation page must include the Apache 2.0 license header. 

4. Do a grammar check of your changes. Use Grammarly if you don't have a more advanced tool at hand.

5. Build the docs locally to test that your changes are applied properly and you didn't break anything.

6. If you added a new page or imported any external files, run the license checker: `mvn clean validate -DskipTests=true -P check-licenses`

Changing the URL of an Existing Page

• Follow this instruction to install `jekyll` and `asciidoctor` on your machine: https://github.com/apache/ignite/blob/IGNITE-7595/docs/README.adoc
• Check out the apache ignite web-site repository (https://github.com/apache/ignite-website)
• Go to the "_docs" folder
• Run `./build.sh --version={version} --github-branch={branch} --latest`
  The script pulls the given branch from the apache-ignite code base repository and generates the docs from the adoc files. The resulting HTML files are located in the "/docs" directory.
  For example:
  ./build.sh --version=2.9.0 --github-branch=IGNITE-7595
   
• Push the generated files to master. They will be published automatically.