Move tutorial pages into a mdbook

Author: 9prady9

Cargo.toml

@@ -15,6 +15,9 @@ exclude = [
     "arrayfire/*",
 ]
 
+[package.metadata.docs.rs]
+rustdoc-args = [ "--html-in-header", "./scripts/mathjax.script", ]
+
 [features]
 algorithm = []
 arithmetic = []

doc/external_docs.css

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# this script meant to be run from the root of arrayfire-rust
+
+cargo rustdoc -- --html-in-header ./scripts/mathjax.script
+
+mdbook build tutorials-book && cp -r tutorials-book/book ./target/doc/arrayfire/

generate_docs.sh

@@ -7,28 +7,25 @@
 //! not be concerned about low-level optimizations that are frequently required to
 //! achieve high throughput on most parallel architectures.
 
-//! This crate provides Rust bindings for the ArrayFire library. Given below table shows the rust bindings compatability with ArrayFire upstream.  If you find any bugs, please report them on [github](https://github.com/arrayfire/arrayfire-rust/issues).
+//! This crate provides Rust bindings for the ArrayFire library. Given below table shows
+//! the rust bindings compatability with ArrayFire upstream.  If you find any bugs,
+//! please report them on [github](https://github.com/arrayfire/arrayfire-rust/issues).
 //!
 //! | arrayfire-rust crate | ArrayFire Upstream |
-//! |:--------------|:---------|
-//! | M.m.p1 | M.m.p2 |
+//! |:--------------------:|:------------------:|
+//! |         M.m.p1       |      M.m.p2        |
 //!
 //! Only, Major(M) & Minor(m) version numbers need to match. *p1* and *p2*
 //! are patch/fix updates for `arrayfire-rust` & `ArrayFire` respectively,
 //! and they don't need to match.
 //!
-//! ## Tutorials
-//!
-//! - [Getting Started with ArrayFire](./getting_started.html)
-//! - [Introduction to Vectorization](./vectorization.html)
-//! - [Array and Matrix Manipulation](./array_and_matrix_manipulation.html)
-//! - [Indexing](./indexing.html)
-//! - [Configure ArrayFire Environment](./configuring_arrayfire_environment.html)
+//! Please go through our [tutorials](./book/index.html) book for more explanations on how to
+//! use ArrayFire to speedup your code.
 
 #![doc(
     html_logo_url = "http://www.arrayfire.com/logos/arrayfire_logo_symbol.png",
     html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-    html_root_url = "http://arrayfire.com/docs/rust"
+    html_root_url = "http://arrayfire.org/arrayfire-rust/arrayfire/index.html"
 )]
 #![warn(missing_docs)]
 #![allow(non_camel_case_types)]

scripts/generate_documentation.sh

@@ -0,0 +1 @@
+book

doc/mathjax.script renamed to scripts/mathjax.script

@@ -0,0 +1,11 @@
+[book]
+authors = ["Pradeep Garigipati"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Rust Wrapper for ArrayFire HPC Library"
+
+[output.html]
+theme = "src/theme"
+mathjax-support = true
+default-theme = "ayu"

src/lib.rs

@@ -0,0 +1,7 @@
+# Summary
+
+- [Getting Started](./getting_started.md)
+- [Introduction to Vectorization](./vectorization.md)
+- [Array and Matrix Manipulation](./array_and_matrix_manipulation.md)
+- [Indexing](./indexing.md)
+- [Configuring ArrayFire Runtime Environment](./configuring_arrayfire_environment.md)

tutorials-book/.gitignore

@@ -1,4 +1,4 @@
-% Array and Matrix Manipulation
+# Array and Matrix Manipulation
 
 ArrayFire provides several different methods for manipulating arrays and matrices.
 The functionality includes:
@@ -16,13 +16,13 @@ Below we provide several examples of these functions and their use.
 
 ### moddims()
 
-The [moddims](./fn.moddims.html) function changes the dimensions of an array without
+The [moddims](../fn.moddims.html) function changes the dimensions of an array without
 changing its data or order. Note that this function modifies only the _metadata_
 associated with the array. It does not modify the content of the array.
 Here is an example of moddims() converting an 8x1 array into a 2x4 and then
 back to a 8x1:
 
-```rust
+```rust,noplaypen
 a [8 1 1 1]
     1.0000
     2.0000
@@ -53,7 +53,7 @@ let out = moddims(&a, a.elements(), 1, 1, 1);
 
 ### flat()
 
-The [flat](./fn.flat.html) function flattens an array to one dimension:
+The [flat](../fn.flat.html) function flattens an array to one dimension:
 
 ```
 a [3 3 1 1]
@@ -76,11 +76,11 @@ flat(&a)
 
 ### flip()
 
-The [flip](./fn.flip.html) function flips the contents of an array along a
+The [flip](../fn.flip.html) function flips the contents of an array along a
 chosen dimension. In the example below, we show the 5x2 array flipped
 along the zeroth (i.e. within a column) and first (e.g. across rows) axes:
 
-```rust
+```rust,noplaypen
 a [5 2 1 1]
     1.0000     6.0000
     2.0000     7.0000
@@ -105,12 +105,12 @@ flip(a, 1) [5 2 1 1]
 
 ### join()
 
-The [join](./fn.join.html), [join_many](./fn.join_many.html) functions can be
+The [join](../fn.join.html), [join_many](../fn.join_many.html) functions can be
 used to join arrays along a specific dimension.
 
 Here is an example of how to use join an array to itself:
 
-```rust
+```rust,noplaypen
 a [5 1 1 1]
     1.0000
     2.0000
@@ -140,11 +140,11 @@ join(1, a, a) [5 2 1 1]
 
 ### reorder()
 
-The [reorder](./fn.reorder.html) function modifies the order of data within an array by
+The [reorder](../fn.reorder.html) function modifies the order of data within an array by
 exchanging data according to the change in dimensionality. The linear ordering
 of data within the array is preserved.
 
-```rust
+```rust,noplaypen
 a [2 2 3 1]
     1.0000     3.0000
     2.0000     4.0000
@@ -181,10 +181,10 @@ reorder(&a, 2, 0, 1)
 
 ### shift()
 
-The [shift](./fn.shift.html) function shifts data in a circular buffer fashion along a
+The [shift](../fn.shift.html) function shifts data in a circular buffer fashion along a
 chosen dimension. Consider the following example:
 
-```rust
+```rust,noplaypen
 a [3 5 1 1]
     0.0000     0.0000     0.0000     0.0000     0.0000
     3.0000     4.0000     5.0000     1.0000     2.0000
@@ -205,11 +205,11 @@ shift(&a, -1, 2 )
 
 ### tile()
 
-The [tile](./fn.tile.html) function repeats an array along the specified dimension.
+The [tile](../fn.tile.html) function repeats an array along the specified dimension.
 For example below we show how to tile an array along the zeroth and first
 dimensions of an array:
 
-```rust
+```rust,noplaypen
 a [3 1 1 1]
     1.0000
     2.0000
@@ -254,10 +254,10 @@ tile(a, tile_dims) [3 2 3 1]
 
 ### transpose()
 
-The [transpose](./fn.transpose.html) function performs a standard matrix transpose. The input
+The [transpose](../fn.transpose.html) function performs a standard matrix transpose. The input
 array must have the dimensions of a 2D-matrix.
 
-```rust
+```rust,noplaypen
 a [3 3 1 1]
     1.0000     3.0000     3.0000
     2.0000     1.0000     3.0000

tutorials-book/book.toml

@@ -1,15 +1,15 @@
-% Configuring Arrayfire Environment
+# Configuring Arrayfire Environment
 
 Following are the list of environment and runtime configurations that will help enhance
 your experience with ArrayFire.
 
-# AF_PATH
+## AF_PATH
 
 This is the path with ArrayFire gets installed, ie. the includes and libs are
 present in this directory. You can use this variable to add include paths and
 libraries to your projects.
 
-# AF_PRINT_ERRORS
+## AF_PRINT_ERRORS
 
 When AF_PRINT_ERRORS is set to 1, the exceptions thrown are more verbose and
 detailed. This helps in locating the exact failure.
@@ -18,10 +18,10 @@ detailed. This helps in locating the exact failure.
 AF_PRINT_ERRORS=1 ./myprogram
 ```
 
-# AF_CUDA_DEFAULT_DEVICE
+## AF_CUDA_DEFAULT_DEVICE
 
 Use this variable to set the default CUDA device. Valid values for this
-variable are the device identifiers shown when [af::info](./fn.info.html) is run.
+variable are the device identifiers shown when [af::info](../fn.info.html) is run.
 
 ```
 AF_CUDA_DEFAULT_DEVICE=1 ./myprogram
@@ -30,19 +30,19 @@ AF_CUDA_DEFAULT_DEVICE=1 ./myprogram
 Note: af::setDevice call in the source code will take precedence over this
 variable.
 
-# AF_OPENCL_DEFAULT_DEVICE
+## AF_OPENCL_DEFAULT_DEVICE
 
 Use this variable to set the default OpenCL device. Valid values for this
-variable are the device identifiers shown when [af::info](./fn.info.html) is run.
+variable are the device identifiers shown when [af::info](../fn.info.html) is run.
 
 ```
 AF_OPENCL_DEFAULT_DEVICE=1 ./myprogram
 ```
 
-Note: [af::set_device](./fn.set_device.html) call in the source code will take precedence over this
+Note: [af::set_device](../fn.set_device.html) call in the source code will take precedence over this
 variable.
 
-# AF_OPENCL_DEFAULT_DEVICE_TYPE
+## AF_OPENCL_DEFAULT_DEVICE_TYPE
 
 Use this variable to set the default OpenCL device type. Valid values for this
 variable are: CPU, GPU, ACC (Accelerators).
@@ -53,9 +53,9 @@ When set, the first device of the specified type is chosen as default device.
 AF_OPENCL_DEFAULT_DEVICE_TYPE=CPU ./myprogram
 ```
 
-Note: `AF_OPENCL_DEFAULT_DEVICE` and [af::set_device](./fn.set_device.html) takes precedence over this variable.
+Note: `AF_OPENCL_DEFAULT_DEVICE` and [af::set_device](../fn.set_device.html) takes precedence over this variable.
 
-# AF_OPENCL_DEVICE_TYPE
+## AF_OPENCL_DEVICE_TYPE
 
 Use this variable to only choose OpenCL devices of specified type. Valid values for this
 variable are:
@@ -71,7 +71,7 @@ When set, the remaining OpenCL device types are ignored by the OpenCL backend.
 AF_OPENCL_DEVICE_TYPE=CPU ./myprogram
 ```
 
-# AF_OPENCL_CPU_OFFLOAD
+## AF_OPENCL_CPU_OFFLOAD
 
 When ArrayFire runs on devices with unified memory with the host (ie.
 `CL_DEVICE_HOST_UNIFIED_MENORY` is true for the device) then certain functions
@@ -92,13 +92,13 @@ Prior to v3.4, CPU Offload functionality was used only when the user set
 From v3.4 onwards, CPU Offload is enabled by default and is disabled only when
 `AF_OPENCL_CPU_OFFLOAD=0` is set.
 
-# AF_OPENCL_SHOW_BUILD_INFO
+## AF_OPENCL_SHOW_BUILD_INFO
 
 This variable is useful when debuggin OpenCL kernel compilation failures. When
 this variable is set to 1, and an error occurs during a OpenCL kernel
 compilation, then the log and kernel are printed to screen.
 
-# AF_DISABLE_GRAPHICS
+## AF_DISABLE_GRAPHICS
 
 Setting this variable to 1 will disable window creation when graphics
 functions are being called. Disabling window creation will disable all other
@@ -109,12 +109,12 @@ without displays. When graphics calls are run on such machines, they will
 print warning about window creation failing. To suppress those calls, set this
 variable.
 
-# AF_SYNCHRONOUS_CALLS
+## AF_SYNCHRONOUS_CALLS
 
 When this environment variable is set to 1, ArrayFire will execute all
 functions synchronously.
 
-# AF_SHOW_LOAD_PATH
+## AF_SHOW_LOAD_PATH
 
 When using the Unified backend, if this variable is set to 1, it will show the
 path where the ArrayFire backend libraries are loaded from.
@@ -123,7 +123,7 @@ If the libraries are loaded from system paths, such as PATH or LD_LIBRARY_PATH
 etc, then it will print "system path". If the libraries are loaded from other
 paths, then those paths are shown in full.
 
-# AF_MEM_DEBUG
+## AF_MEM_DEBUG
 
 When AF_MEM_DEBUG is set to 1 (or anything not equal to 0), the caching mechanism in the memory manager is disabled.
 The device buffers are allocated using native functions as needed and freed when going out of scope.
@@ -134,27 +134,27 @@ When the environment variable is not set, it is treated to be non zero.
 AF_MEM_DEBUG=1 ./myprogram
 ```
 
-# AF_MAX_BUFFERS
+## AF_MAX_BUFFERS
 
 When AF_MAX_BUFFERS is set, this environment variable specifies the maximum number of buffers allocated before garbage collection kicks in.
 
 Please note that the total number of buffers that can exist simultaneously can be higher than this number. This variable tells the garbage collector that it should free any available buffers immediately if the treshold is reached.
 
 When not set, the default value is 1000.
 
-# AF_OPENCL_MAX_JIT_LEN
+## AF_OPENCL_MAX_JIT_LEN
 
 When set, this environment variable specifies the maximum height of the OpenCL JIT tree after which evaluation is forced.
 
 The default value, as of v3.4, is 50 on OSX, 100 everywhere else. This value was 20 for older versions.
 
-# AF_CUDA_MAX_JIT_LEN
+## AF_CUDA_MAX_JIT_LEN
 
 When set, this environment variable specifies the maximum height of the CUDA JIT tree after which evaluation is forced.
 
 The default value, as of v3.4, 100. This value was 20 for older versions.
 
-# AF_CPU_MAX_JIT_LEN
+## AF_CPU_MAX_JIT_LEN
 
 When set, this environment variable specifies the maximum length of the CPU JIT tree after which evaluation is forced.