Skip to content
Permalink
Browse files
Creating a formal asciidoc (#131)
  • Loading branch information
IgGusev committed Apr 26, 2022
1 parent ee9d84a commit 34db3cdee91e3cd212ac018116f17ddb6a07d9e0
Showing 113 changed files with 7,341 additions and 0 deletions.
@@ -0,0 +1,5 @@
.jekyll-cache/
_site/
Gemfile.lock
.jekyll-metadata

@@ -0,0 +1,17 @@
source "https://rubygems.org"

# git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

gem 'asciidoctor'
gem 'jekyll', group: :jekyll_plugins
gem 'wdm', '~> 0.1.1' if Gem.win_platform?
group :jekyll_plugins do
gem 'jekyll-asciidoc'
end
#gem 'pygments.rb', '~> 1.2.1'
gem 'thread_safe', '~> 0.3.6'
gem 'slim', '~> 4.0.1'
gem 'tilt', '~> 2.0.9'

# Ruby 3.0.0 requires dependency which doesn't contains in the bundle
gem "webrick", "~> 1.7"
@@ -0,0 +1,252 @@
// 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]
----
@@ -0,0 +1,41 @@
# 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.
exclude: [guidelines.md, "Gemfile", "Gemfile.lock", README.adoc, "_docs/code-snippets", "_docs/includes", '*.sh']
attrs: &asciidoc_attributes
version: 1.0
base_url: /docs
stylesdir: /docs/assets/css
imagesdir: /docs
source-highlighter: rouge
table-stripes: even
collections:
docs:
permalink: /docs/:path:output_ext
output: true
defaults:
-
scope:
path: ''
values:
layout: 'doc'
-
scope:
path: '_docs'
values:
toc: ignite
asciidoctor:
base_dir: _docs/
attributes: *asciidoc_attributes

@@ -0,0 +1,58 @@
# 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.
- title: Amazon S3 IP Finder
url: aws/aws
- title: Apache Camel Streamer
url: camel/camel-streamer
- title: Apache Flink Streamer
url: flink/flink-streamer
- title: Apache Flume Sink
url: flume/flume-sink
- title: Apache Ignite Azure Module
url: azure/azure
- title: Apache Ignite GCE Module
url: gce/gce
- title: Apache Ignite Pub/Sub Module
url: pub-sub/pub-sub
- title: Apache Ignite and Spring Boot
url: spring/spring-boot
- title: Apache Ignite and Spring Data
url: spring/spring-data
- title: Apache Ignite and Spring Cache
url: spring/spring-caching
- title: Apache Ignite and Spring Transactions
url: spring/spring-tx
- title: Apache Kafka Streamer
url: kafka/kafka-streamer
- title: Apache Storm Streamer
url: storm/storm-streamer
- title: Change Data Capture Extension
url: cdc/change-data-capture-extensions
- title: JMS Streamer
url: jms/jms-streamer
- title: MQTT Streamer
url: mqtt/mqtt-streamer
- title: Performance Statistics Extension
url: perf-statistics/performance-statistics
- title: RocketMQ Streamer
url: rocketmq/rocketmq-streamer
- title: Topology Validator
url: topology-validator/topology-validator
- title: Twitter Streamer
url: twitter/twitter-streamer
- title: ZeroMQ Streamer
url: zeromq/zeromq-streamer
- title: ZooKeeper IP Finder
url: zookeeper/zookeeper-ip

0 comments on commit 34db3cd

Please sign in to comment.