Table of Contents |
---|
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:
Info | ||||||
---|---|---|---|---|---|---|
| ||||||
Download the archive below if you're looking for a documentation page that existed on the legacy documentation portal - https://apacheignite.readme.io
|
The sections below cover the code contribution and publication processes in detail.
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.
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:
Find documentation sources under the ignite_root/docs/_docs directory and do necessary modifications:
Do a grammar check of your changes. Use Grammarly if you don't have a more advanced tool at hand.
If you added a new page or imported any external files, run the license checker: `mvn clean validate -DskipTests=true -P check-licenses`
Send a pull-request to the Ignite master, request the review from documentation maintainers.
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.
Info |
---|
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:
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
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.
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.
./build.sh --version=2.9.1 --github-branch=ignite-2.9.1 --latest
./build.sh --version=2.9.0 --github-branch=ignite-2.9-docs
RewriteRule ^docs/latest/(.*)$ /docs/2.9.1/$1 [L]
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
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.
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
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).
Docs Scope | Maintainers |
---|---|
All docs | Nikita Safonov (nsafonov@gridgain.com), Igor Gusev (igusev@gridgain.com) |
.NET-specific docs maintainers | Pavel Tupitsyn (ptupitsyn@apache.org) |
C++, Python, Node.JS, PHP-specific docs | Igor Sapego (isapego@gridgain.com) |
Presently, all the documentation is hosted on readme.io engine.
Follow these rules if you plan to update an existing documentation describing a new feature or capability that is unavailable in a current public Apache Ignite release.