docs/README.adoc - ignite-extensions - Git at Google

 // Licensed to the Apache Software Foundation (ASF) under one or more
 // contributor license agreements.  See the NOTICE file distributed with
 // this work for additional information regarding copyright ownership.
 // The ASF licenses this file to You under the Apache License, Version 2.0
 // (the "License"); you may not use this file except in compliance with
 // the License.  You may obtain a copy of the License at
 //
 // http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 = Apache Ignite Extensions Documentation
 :toc:
 :toc-title:

 == Overview
 The Apache Ignite Extensions 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 link:https://asciidoctor.org/docs/what-is-asciidoc/[asciidoc].
 The Asciidoc files are compiled into HTML pages and published to https://ignite.apache.org/docs.


 .Content of the “docs” directory
 [cols="1,4",opts="stretch"]
 |===
 | pass:[_]docs  | The directory with .adoc files and code-snippets.
 | pass:[_]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

 . Install Jekyll by following this instruction:  https://jekyllrb.com/docs/installation/[window=_blank]
 . In the “/docs” directory, run the following command:
 +
 [source, shell]
 ----
 $ bundle
 ----
 +
 This should install all dependencies, including `asciidoctor`.
 . Start jekyll:
 +
 [source, shell]
 ----
 $ bundle exec jekyll s
 ----
 The command compiles the Asciidoc files into HTML pages and starts a local webserver.

 Open `http://localhost:4000/docs[window=_blank]` 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.

 [source, shell]
 ----
 $ docker run -v "$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll:latest jekyll s
 ----

 Open `http://localhost:4000/docs[window=_blank]` 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: https://github.com/ffi/ffi/issues/653

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

 [source, text]
 ----
 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 link:https://asciidoctor.org/docs/asciidoc-recommended-practices:[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:
 [source, adoc]
 ----
 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:

 [source, adoc]
 ----
 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.

 ```asciidoc
 [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]
 ====
 [discrete]
 === Callout Title
 Callout Text
 ====

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

 [CAUTION]
 ====
 [discrete]
 === 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:
 +
 [source, adoc,subs="macros"]
 ----
 \include::{javaCodeDir}/JavaThinClient.java[tag=clientConnection,indent=0]
 ----
	// Licensed to the Apache Software Foundation (ASF) under one or more
	// contributor license agreements. See the NOTICE file distributed with
	// this work for additional information regarding copyright ownership.
	// The ASF licenses this file to You under the Apache License, Version 2.0
	// (the "License"); you may not use this file except in compliance with
	// the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	= Apache Ignite Extensions Documentation
	:toc:
	:toc-title:

	== Overview
	The Apache Ignite Extensions 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 link:https://asciidoctor.org/docs/what-is-asciidoc/[asciidoc].
	The Asciidoc files are compiled into HTML pages and published to https://ignite.apache.org/docs.


	.Content of the “docs” directory
	[cols="1,4",opts="stretch"]
	\|===
	\| pass:[_]docs \| The directory with .adoc files and code-snippets.
	\| pass:[_]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

	. Install Jekyll by following this instruction: https://jekyllrb.com/docs/installation/[window=_blank]
	. In the “/docs” directory, run the following command:
	+
	[source, shell]
	----
	$ bundle
	----
	+
	This should install all dependencies, including `asciidoctor`.
	. Start jekyll:
	+
	[source, shell]
	----
	$ bundle exec jekyll s
	----
	The command compiles the Asciidoc files into HTML pages and starts a local webserver.

	Open `http://localhost:4000/docs[window=_blank]` 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.

	[source, shell]
	----
	$ docker run -v "$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll:latest jekyll s
	----

	Open `http://localhost:4000/docs[window=_blank]` 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: https://github.com/ffi/ffi/issues/653

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

	[source, text]
	----
	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 link:https://asciidoctor.org/docs/asciidoc-recommended-practices:[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:
	[source, adoc]
	----
	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:

	[source, adoc]
	----
	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.

	```asciidoc
	[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]
	====
	[discrete]
	=== Callout Title
	Callout Text
	====

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

	[CAUTION]
	====
	[discrete]
	=== 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:
	+
	[source, adoc,subs="macros"]
	----
	\include::{javaCodeDir}/JavaThinClient.java[tag=clientConnection,indent=0]
	----