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:

Image Modified

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

...

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/_docsdata/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. (optional) 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`

7. Send a pull-request to the Ignite master, request the review from documentation maintainers.

8. Merge the changes after passing the review and after you confirm that all the automated checks performed by Travis CI are passed.
9. If applicable, cherry-pick the commit to the latest version of the docs (that is already published on the website or to be released).

Contributing Minor Changes

...

Under the minor changes, we assume the fixing of typos, misprints, or easy-to-fix unclarities. In general, you're dealing with a minor change if it takes you a longer time to create a JIRA ticket and get a pull-request figured.

Do the following to do a minor change:

1. Follow Contributing Significant Changes and feel free to take shortcuts here:
   • You can skip the creation of a JIRA ticket
   • You can skip the creation of a pull-request
2. Commit the changes to the repo using this "ignite docs: <what was changed>" commit message.

Updating Released Docs

Once a documentation update is merged to the master branch, cherry-pick it to the latest published version on the website or to a version that is to be released

1. Cherry-pick a commit from the master into ignite-{version} branch.
2. If ignite-{version} is the latest version that is already published on the website, then republish the docs following this process: Updating Published Docs

Changing an URL of an Existing Page

...

If you rename an already published page or change the page's path in the ignite_root/docs/_data/toc.yaml file, you must configure a proper redirect from the old to the new URL in the following files of the Ignite website:

https://github.com/apache/ignite-website/blob/

...

master/.htaccess

Reach out to documentation maintainers if you need any help with this.

Publishing to the Website

While the documentation sources are stored in the AsciiDoc format in the main Ignite repository, the version of the docs, that is published on the website, is stored in the Ignite website repo in the HTML format. This section explains how to publish documentation changes to the website.

Prerequisite 

• Set up the website locally: Website Development
• Install the Jekyll toolchain following this instruction: https://jekyllrb.com/docs/installation/

Publishing New Version

1. The docs are always published from a release-specific branch, such as ignite-2.9.1 (the only exception is version 2.9.0 that was published from ignite-2.9.1-docs)
2. In the release branch, open the docs/_config.yml file and update the version property with the release number.
3. Push all the changes to the release branch.
4. Checkout the ignite-website repo: Website Development
5. Go to the ignite_website/_docs directory.
6. Run the `./build.sh --version={version} --github-branch={branch} --latest` command to transform the docs from the AsciiDoc to the HTML format, and add the HTML files to the website repository
   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.1 --github-branch=ignite-2.9.1 --latest

7. Check that the version of the docs was generated without issues using your local installation of the website: http://localhost/docs/latest/
8. In order to update all internal links on the previous ‘latest’ docs and to add `noindex`, it’s necessary to rebuild it. This is done by repeating step #3, but without the `--latest` parameter and using the previous version data.
   For example:

   ./build.sh --version=2.9.0 --github-branch=

...

1. ignite-2.9-docs

2. Update the following line in .htaccess file so the /docs/latest/ redirects to the new version: 

   RewriteRule ^docs/latest/(.*)$ /docs/2.9.1/$1 [L]

3. Push the generated files to the ignite website master. They will be published automatically.
4. Check that the version was published successfully on the Ignite website: https://ignite.apache.org/docs/latest/

NOTE: The docs for Ignite 3.x can be published on the same way, the script will detect it and pull the content from the respective repo. For example: 

./build.sh --version=3.0.0-alpha1 --github-branch=ignite-3.0.0-alpha1

Updating Published Docs

The GitHub Action is used to automatically update documentation for released versions. (Supports 2.x versions since 2.10)

The push event to a released branch triggers script to publish changes to the site.

Commit changes to the Ignite repository and make sure that the site updated.

Manual update (2.9 and older, 3.x)

Use the same command to generate an updated version of already released docs:

 ./build.sh --version=2.9.0 --github-branch=ignite-2.9-docs

As for the rest, follow the procedure described in the Publishing New Version section above, except for step #5.

If you are rebuilding the docs for the latest Ignite version, remember to use '--latest' flag 

Documentation Feedback via Bugyard

There is a "Docs Feedback" button in the bottom right corner of all documentation pages, which allows anyone to leave comments.

Those comments go to https://app.bugyard.io/. Credentials are at https://svn.apache.org/repos/private/pmc/ignite/credentials/bugyard.io (PMC only area, use Apache ID to access).

...