Reorganize guide structure

membraneframework-labs · Mar 27, 2019 · a5e82b6 · a5e82b6
1 parent 843d3e2
commit a5e82b6
Show file tree

Hide file tree

Showing 17 changed files with 196 additions and 57 deletions.
diff --git a/.bookignore b/.bookignore
@@ -2,3 +2,4 @@
 *.yml
 *.sh
 package-lock.json
+.vscode
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,9 @@
+secrets.sh
+
+# Created by https://www.gitignore.io/api/vim,node,gitbook,visualstudiocode
+# Edit at https://www.gitignore.io/?templates=vim,node,gitbook,visualstudiocode
+
+### GitBook ###
 # Node rules:
 ## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
 .grunt
@@ -13,4 +19,121 @@ _book
 # eBook build output
 *.epub
 *.mobi
-*.pdf
+*.pdf
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+### Vim ###
+# Swap
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# Session
+Session.vim
+
+# Temporary
+.netrwhist
+*~
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+
+# End of https://www.gitignore.io/api/vim,node,gitbook,visualstudiocode
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,16 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build GitBook",
+            "type": "shell",
+            "command": "./node_modules/gitbook-cli/bin/gitbook.js build",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -1,13 +1,22 @@
 # Summary
 
 * [Introduction](README.md)
-* [Basic concepts](chapter1.md)
-  * [Elements](chapter1/concepts.md)
-  * [First pipeline](chapter1/pipeline.md)
-  * [First element](chapter1/element.md)
-* [Advanced](chapter2.md)
-  * [Logger](chapter2/logger.md)
-  * [NIFs](chapter2/nifs.md)
-  * [Demands](chapter2/demands.md)
-  * [Element lifecycle](chapter2/lifecycle.md)
-  * [Testing](chapter2/testing.md)
+
+## Concepts
+
+* [Elements](concepts/elements.md)
+  * [Pads](concepts/pads.md)
+  * [Lifecycle](concepts/lifecycle.md)
+* [Pipelines](concepts/pipelines.md)
+
+## Building application
+
+* [Writing pipeline](creating_app/pipeline.md)
+* [Logger](creating_app/logger.md)
+
+## Creating new elements
+
+* [Tutorial](creating_element/tutorial.md)
+* [Testing](creating_element/testing.md)
+* [Native code integration](creating_element/natives.md)
+* [Demands](creating_element/demands.md)
diff --git a/chapter1.md b/chapter1.md
diff --git a/chapter1/concepts.md b/chapter1/concepts.md
diff --git a/chapter2.md b/chapter2.md
diff --git a/concepts/elements.md b/concepts/elements.md
@@ -0,0 +1,24 @@
+# Elements
+
+Elements in Membrane Framework are the most basic entities
+responsible for processing multimedia.
+Each instance of an element is an Erlang process, that has internal state and communicates by message passing.
+
+Every element is created to solve one problem. The examples of elements are
+audio encoder (converting raw audio to encoded format like MP3),
+file source (reading data from a file and passing it to other elements) or
+UDP sink (sending data from an application via UDP socket).
+
+There are three basic types of elements: `sink`, `source`, and `filters`:
+
+* `Source` - responsible for getting (or generating) data delivering it to other elements
+* `Sink` - defines an endpoint for data flowing through an application.
+* `Filter` - an element that receives data from other elements, processes it and sends it further to the next elements
+
+Every element may be in one of three states:
+
+* `:stopped` - element has been created
+* `:prepared` - element should be ready for processing data. All necessary resources should be allocated and initialized.
+* `:playing` - element is actually processing data
+
+Elements define their own `options` that parametrize their work. For example, some audio decoder may have an option named `bitrate` that represents bitrate of the output data.
diff --git a/chapter2/lifecycle.md → concepts/lifecycle.md b/chapter2/lifecycle.md → concepts/lifecycle.md
diff --git a/concepts/pads.md b/concepts/pads.md
@@ -0,0 +1,7 @@
+## Pads and capabilities
+
+To create the flow of data between elements in the application, they have to communicate with each other. For that purpose, the concept of `pads` and `capabilities` is used. `Pads` are basically inputs and outputs of the elements and because of that, there are two types of pads: `input` and `output`. It is worth mentioning that `Source` elements may only contain `output` pads, `Sinks` contain only `input` pads, and `Filters` can have both of them.
+
+Every pad has some capabilities, which defines a type of data that it is expecting. This format can be, for example, raw audio with a specific sample rate or encoded audio in a given format.
+
+Two elements that should send data between each other, should have linked pads. One pad can be linked with only one other pad of a different element. Only links between `output` and `input` pads are allowed. Furthermore, to link two pads, their capabilities have to be compatible.
diff --git a/concepts/pipelines.md b/concepts/pipelines.md
@@ -0,0 +1,5 @@
+## Pipelines
+
+A pipeline is a container that consists of many elements and links between them. Like an Element, every Pipeline also has a playback state and on its basis, it manages the state of the contained elements.
+
+During the application execution, elements may want to signal some events. For that purpose, they send the `notification` to their supervisor, which in most cases is a pipeline. A programmer can handle those notifications by defining the appropriate method in the pipeline module.
diff --git a/chapter2/logger.md → creating_app/logger.md b/chapter2/logger.md → creating_app/logger.md
diff --git a/chapter1/pipeline.md → creating_app/pipeline.md b/chapter1/pipeline.md → creating_app/pipeline.md
diff --git a/chapter2/demands.md → creating_element/demands.md b/chapter2/demands.md → creating_element/demands.md
diff --git a/chapter2/nifs.md → creating_element/natives.md b/chapter2/nifs.md → creating_element/natives.md
diff --git a/chapter2/testing.md → creating_element/testing.md b/chapter2/testing.md → creating_element/testing.md
diff --git a/chapter1/element.md → creating_element/tutorial.md b/chapter1/element.md → creating_element/tutorial.md