Child pages
  • How to Document
Skip to end of metadata
Go to start of metadata

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/_data/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`

  7. Send a pull-request, 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.

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.

Only Ignite committers can go through this relaxed contribution process. Contributors need to follow Contributing Significant Changes.

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 an Ignite version is released, the release branch gets frozen and you won't be able to commit to it any changes (including documentation updates). This section explains how to update the docs in such conditions:

  1. Check if the ignite-{version}-docs branch has already been created after the version was released.
  2. If the branch doesn't exist, create it from the ignite-{version} branch.
  3. Commit the changes to the Ignite master.
  4. Cherry-pick the changes to the ignite-{version}-docs branch.
  5. Made the change visible on the website: 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 

Publishing New Version

  1. Pull the latest changes from the website's master branch.
  2. Go to the ignite_website_root/_docs directory.
  3. 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.0 --github-branch=IGNITE-2.9 --latest
  4. Change that the version of the docs was generated without issues using your local installation of the website: http://localhost/docs/latest/
  5. Push the generated files to the ignite website master. They will be published automatically.
  6. Check that the version was published successfully on the Ignite website: https://ignite.apache.org/docs/latest/

Updating Published Docs

Use the same command to generate an updated version of already released docs but do NOT specify the "–latest" flag:

 ./build.sh --version=2.8.0 --github-branch=IGNITE-2.8-docs


As for the rest, follow the procedure described in the Publishing New Version section above.


Documentation Maintainers


Docs ScopeMaintainers

All docs

Denis Magda (dmagda@apache.org)

.NET-specific docs maintainers

Pavel Tupitsyn (ptupitsyn@apache.org)

C++, Python, Node.JS, PHP-specific docs

Igor Sapego (isapego@gridgain.com)

  • No labels