...
Info |
---|
title | Legacy Readme.io Documentation |
---|
|
Download the archive below if you're looking for a documentation page that existed on the legacy documentation portal - https://apacheignite.readme.io View file |
---|
name | legacy_readme_documentation.zip |
---|
height | 250 |
---|
|
|
...
- 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.
- Make sure a JIRA ticket is created for the change and the component property is set to documentation.
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.
Do a grammar check of your changes. Use Grammarly if you don't have a more advanced tool at hand.
- (optional) Build the docs locally to test that your changes are applied properly and you didn't break anything.
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.
- Merge the changes after passing the review and after you confirm that all the automated checks performed by Travis CI are passed.
- If applicable, cherry-pick the commit to the latest version of the docs (that is already published on the website or to be released).
...
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: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
- Cherry-pick a commit from the master into
- Check if the ignite-{version}-docs branch has already been created after the version was released.
- If the branch doesn't exist, create it from the ignite-{version} branch.
- Commit the changes to the Ignite master.
- Cherry-pick the changes to the If ignite-{version} -docs branch.Made the change visible 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
...
https://github.com/apache/ignite-website/blob/master/.htaccess
Reach out to documentation maintainers if you need any help with this.
...
- Set up the website locally: Website Development
- Install the Jekyll toolchain following this instruction: https://jekyllrb.com/docs/installation/
Publishing New Version
- 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)
- In the release branch, open the docs/_config.yml file and update the version property with the release number.
- Push all the changes to the release branch.
- Checkout the ignite-website repo: Website DevelopmentPull the latest changes from the website's master branch.
- Go to the ignite_website_root/_docs directory.
- 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
- Check that the version of the docs was generated without issues using your local installation of the website: http://localhost/docs/latest/
- 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=ignite-2.9-docs
- 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]
- Push the generated files to the ignite website master. They will be published automatically.
- 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.89.0 --github-branch=IGNITEignite-2.89-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).
Documentation Maintainers
...