apache-ignite

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

19
== Overview
20
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.
21

22

23
The Apache Ignite documentation is written in link:https://asciidoctor.org/docs/what-is-asciidoc/[asciidoc].
24
The Asciidoc files are compiled into HTML pages and published to https://ignite.apache.org/docs.
25

26

27
.Content of the “docs” directory
28
[cols="1,4",opts="stretch"]
29
|===
30
| pass:[_]docs  | The directory with .adoc files and code-snippets.
31
| pass:[_]config.yml | Jekyll configuration file.
32
|===
33

34

35
== Building the Docs Locally
36

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

39
=== Install Jekyll and Asciidoctor
40

41
. Install Jekyll by following this instruction:  https://jekyllrb.com/docs/installation/[window=_blank]
42
. In the “/docs” directory, run the following command:
43
+
44
[source, shell]
45
----
46
$ bundle
47
----
48
+
49
This should install all dependencies, including `asciidoctor`.
50
. Start jekyll:
51
+
52
[source, shell]
53
----
54
$ bundle exec jekyll s
55
----
56
The command compiles the Asciidoc files into HTML pages and starts a local webserver.
57

58
Open `http://localhost:4000/docs[window=_blank]` in your browser.
59

60
=== Run with Docker
61

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

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

69
Open `http://localhost:4000/docs[window=_blank]` in your browser.
70

71
=== Troubleshooting
72

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

76
==== MacOS: Issues with FFI library during Jekyll installation
77

78
You should see an error trace similar to this: https://github.com/ffi/ffi/issues/653
79

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

82
[source, text]
83
----
84
brew reinstall libffi
85
export LDFLAGS="-L/usr/local/opt/libffi/lib"
86
export CPPFLAGS="-I/usr/local/opt/libffi/include"
87
export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"
88
gem install --user-install bundler jekyll
89
----
90

91
==== MacOS: jekyll-asciidoc gem is not installed by default
92

93
Try to follow this procedure to fix the issue.
94

95
* 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.
96
* Run `build.sh` (fails with `Could not find gem 'jekyll-asciidoc'...` error).
97
* Go to `tmp/web_site` folder.
98
* Run `bundle install`.
99
* Revert the `build.sh` script and run it again.
100

101
==== MacOS: can't build project due to inability to load openssl
102

103
You should see an error like this:
104

105
`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
106
   Referenced from: /Users/dmagda/.rbenv/versions/2.6.2/lib/ruby/2.6.0/x86_64-darwin18/digest/sha1.bundle`
107

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

111
== How to Contribute
112

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

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

118
* 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.
119
* 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.
120

121

122
The following sections explain specific asciidoc syntax that we use.
123

124
=== Table of content
125

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

129
=== Changing an URL of an existing page
130

131
If you rename an already published page or change the page's path in the `/_data/toc.yaml` file,
132
you must configure a proper redirect from the old to the new URL in the following files of the Ignite website:
133
https://github.com/apache/ignite-website/blob/master/.htaccess
134

135
Reach out to documentation maintainers if you need any help with this.
136

137
=== Links to other sections in the docs
138
All .adoc files are located in the "docs/_docs" directory.
139
Any link to the files within the directory must be relative to that directory.
140
Remove the file extension (.adoc).
141

142
For example:
143
[source, adoc]
144
----
145
link:persistence/native-persistence[Native Persistence]
146
----
147

148
This is a link to the Native Persistence page.
149

150
=== Links to external resources
151

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

154
[source, adoc]
155
----
156
link:https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSE_Protocols[Supported protocols,window=_blank]
157
----
158

159

160
=== Tabs
161

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

164
Tabs are defined by the `tabs` block:
165
```
166
[tabs]
167
--
168
individual tabs are defined here
169
--
170
```
171

172
Each tab is defined by the 'tab' directive:
173

174
```
175
tab:tab_name[]
176
```
177

178
where `tab_name` is the title of the tab.
179

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

182
```asciidoc
183
[tabs]
184
--
185
tab:XML[]
186

187
The content of the XML tab goes here
188

189
tab:Java[]
190

191
The content of the Java tab is here
192

193
tab:C#/.NET[]
194

195
tab:C++[unsupported]
196

197
--
198
```
199

200
=== Callouts
201

202
Use the syntax below if you need to bring reader's attention to some details:
203

204
[NOTE]
205
====
206
[discrete]
207
=== Callout Title
208
Callout Text
209
====
210

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

213
[CAUTION]
214
====
215
[discrete]
216
=== Callout Title
217
Callout Text
218
====
219

220
=== Code Snippets
221

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

226

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

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

231
* 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.
232
For example:
233
+
234
```
235
[source, java]
236
----
237
// tag::clientConnection[]
238
ClientConfiguration cfg = new ClientConfiguration().setAddresses("127.0.0.1:10800");
239
try (IgniteClient client = Ignition.startClient(cfg)) {
240
    ClientCache<Integer, String> cache = client.cache("myCache");
241
    // get data from the cache
242
}
243
// end::clientConnection[]
244
----
245
```
246

247
* Include the tag in the adoc file:
248
+
249
[source, adoc,subs="macros"]
250
----
251
\include::{javaCodeDir}/JavaThinClient.java[tag=clientConnection,indent=0]
252
----
253