Apache Ignite Documentation

• Overview
• Building the Docs Locally
  • Install Jekyll and Asciidoctor
  • Run with Docker
  • Troubleshooting
• How to Contribute
  • Table of content
  • Changing an URL of an existing page
  • Links to other sections in the docs
  • Links to external resources
  • Tabs
  • Callouts
  • Code Snippets

Overview

The Apache Ignite documentation is maintained in the repository with the code base, in the "/docs" subdirectory. The directory contains the source files, HTML templates and css styles.

The Apache Ignite documentation is written in asciidoc. The Asciidoc files are compiled into HTML pages and published to https://ignite.apache.org/docs.

Table 1. Content of the “docs” directory

_docs	The directory with .adoc files and code-snippets.
_config.yml	Jekyll configuration file.

Building the Docs Locally

To build the docs locally, you can install jekyll and other dependencies on your machine, or you can use Jekyll docker image.

Install Jekyll and Asciidoctor

1. Install Jekyll by following this instruction: https://jekyllrb.com/docs/installation/

2. In the “/docs” directory, run the following command:

   $ bundle

   This should install all dependencies, including asciidoctor.

3. Start jekyll:

   $ bundle exec jekyll s

   The command compiles the Asciidoc files into HTML pages and starts a local webserver.

Open http://localhost:4000/docs in your browser.

Run with Docker

The following command starts jekyll in a container and downloads all dependencies. Run the command in the “/docs” directory.

$ docker run -v "$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll:latest jekyll s

Open http://localhost:4000/docs in your browser.

Troubleshooting

Below are some issues you might hit during an installation of the Jekyll environment or while building the tutorials. Let us know if you come across a new and found a workaround.

MacOS: Issues with FFI library during Jekyll installation

You should see an error trace similar to this: ffi/ffi#653

Attempt to fix the problem by following this sequence of commands (typically it’s the last command only):

brew reinstall libffi
export LDFLAGS="-L/usr/local/opt/libffi/lib"
export CPPFLAGS="-I/usr/local/opt/libffi/include"
export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"
gem install --user-install bundler jekyll

MacOS: jekyll-asciidoc gem is not installed by default

Try to follow this procedure to fix the issue.

• Comment out the rm -rf $tmp_dir at the very end of the build.sh script, so that the temp folder is not deleted after the execution.

• Run build.sh (fails with Could not find gem 'jekyll-asciidoc'…​ error).

• Go to tmp/web_site folder.

• Run bundle install.

• Revert the build.sh script and run it again.

MacOS: can’t build project due to inability to load openssl

You should see an error like this:

LoadError: dlopen(/Users/dmagda/.rbenv/versions/2.6.2/lib/ruby/2.6.0/x86_64-darwin18/digest/sha1.bundle, 9): Library not loaded: /usr/local/opt/openssl/lib/libssl.1.0.0.dylib Referenced from: /Users/dmagda/.rbenv/versions/2.6.2/lib/ruby/2.6.0/x86_64-darwin18/digest/sha1.bundle

Try to upgrade Ruby, rbenv to the latest version (2.7.1) and then reinstall Jekyll. Use the official instructions: https://jekyllrb.com/docs/installation/

How to Contribute

If you want to contribute to the documentation, add or modify the relevant page in the docs/_docs directory. This directory contains all .adoc files (which are then rendered into HTML pages and published on the web-site).

Because we use asciidoc for documentation, consider the following points:

• Get familiar with the asciidoc format: https://asciidoctor.org/docs/user-manual/. You don’t have to read the entire manual. Search through it when you want to learn how to create a numbered list, or insert an image, or use italics.

• Please read the AsciiDoc Recommended Practices and try to adhere to those when editing the .adoc source files.

The following sections explain specific asciidoc syntax that we use.

Table of content

The table of content is defined in the _data/toc.yaml file. If you want to add a new page, make sure to update the TOC.

Changing an URL of an existing page

If you rename an already published page or change the page’s path in the /_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.

Links to other sections in the docs

All .adoc files are located in the "docs/_docs" directory. Any link to the files within the directory must be relative to that directory. Remove the file extension (.adoc).

For example:

link:persistence/native-persistence[Native Persistence]

This is a link to the Native Persistence page.

Links to external resources

When referencing an external resource, make the link to open in a new window by adding the window=_blank attribute:

link:https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSE_Protocols[Supported protocols,window=_blank]

Tabs

We use custom syntax to insert tabs. Tabs are used to provide code samples for different programming languages.

Tabs are defined by the tabs block:

[tabs]
--
individual tabs are defined here
--

Each tab is defined by the 'tab' directive:

tab:tab_name[]

where tab_name is the title of the tab.

The content of the tab is everything that is given between the tab title, and the next tab or the end of the block.

[tabs]
--
tab:XML[]

The content of the XML tab goes here

tab:Java[]

The content of the Java tab is here

tab:C#/.NET[]

tab:C++[unsupported]

--

Callouts

Use the syntax below if you need to bring reader’s attention to some details:

Note	Callout Title Callout Text

Change the callout type to CAUTION if you want to put out a warning:

Caution

Callout Title Callout Text

Code Snippets

Code snippets must be taken from a compilable source code file (e.g. java, cs, js, etc). We use the include feature of asciidoc. Source code files are located in the docs/_docs/code-snippets/{language} folders.

To add a code snippet to a page, follow these steps:

• Create a file in the code snippets directory, e.g. _docs/code-snippets/java/org/apache/ignite/snippets/JavaThinClient.java

• Enclose the piece of code you want to include within named tags (see https://asciidoctor.org/docs/user-manual/#by-tagged-regions). Give the tag a self-evident name. For example:

  [source, java]
  ----
  // tag::clientConnection[]
  ClientConfiguration cfg = new ClientConfiguration().setAddresses("127.0.0.1:10800");
  try (IgniteClient client = Ignition.startClient(cfg)) {
      ClientCache<Integer, String> cache = client.cache("myCache");
      // get data from the cache
  }
  // end::clientConnection[]
  ----

• Include the tag in the adoc file:

  include::{javaCodeDir}/JavaThinClient.java[tag=clientConnection,indent=0]