Auto merge of #24 - autumnai:docs, r=hobofan

docs/everything: add documentation guidelines and apply it to the whole library

CLOSES #13

CONTRIBUTING.md

@@ -9,6 +9,7 @@ overview of how you can contribute to Leaf.
 * [Feature Requests](#feature-requests)
 * [Appendix](#appendix)
   * [Git Commit Guidelines](#git-commit-guidelines)
+  * [Documentation Guidelines](#documentation-guidelines)
 
 
 If you have questions hop on the [Leaf Chat](https://gitter.im/autumnai/leaf)
@@ -58,7 +59,7 @@ on the pull request with an `r+`. It will look something like this:
 
 This tells @homu, our lovable integration bot, that your pull request has
 been approved. The PR then enters the
-[merge queue][http://buildbot.rust-lang.org/homu/queue/rust], where
+[merge queue](http://buildbot.rust-lang.org/homu/queue/rust), where
 @homu will run all the tests on every platform we support. If it all works
 out, @homu will merge your code into `master` and close the pull request.
 
@@ -181,3 +182,11 @@ If the commit reverts a previous commit, it should begin with `revert:`,
 followed by the header of the reverted commit. In the body it should say:
 `This reverts commit <hash>.`, where the hash is the SHA of the commit being
 reverted.
+
+### Documentation Guidelines
+
+We created an extensive [Documentation Guide][1] for you, which outlines an easy
+and efficient communication Framework for providing developers and users with
+helpful Documentation about the Deep Learning Framework.
+
+[1] https://medium.com/@autumn_eng/increasing-open-source-engagement-with-structural-communication-guidelines-for-code-documentation-e72533de8e45

Cargo.toml

@@ -14,10 +14,10 @@ keywords = ["deep-learning", "neural-networks", "machine-learning", "framework"]
 license = "MIT"
 
 [dependencies]
-phloem = "0.2.2"
+phloem = "0.2.4"
 rblas = "0.0.9"
 log = "0.3.2"
-clippy = "~0.0.22"
+clippy = "0.0.23"
 
 [features]
 default = []

README.md

@@ -1,44 +1,149 @@
 # Leaf • [![Join the chat at https://gitter.im/autumnai/leaf](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/autumnai/leaf?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://travis-ci.org/autumnai/leaf.svg?branch=master)](https://travis-ci.org/autumnai/leaf) [![Coverage Status](https://coveralls.io/repos/autumnai/leaf/badge.svg?branch=master&service=github)](https://coveralls.io/github/autumnai/leaf?branch=master) [![Crates.io](http://meritbadge.herokuapp.com/leaf)](https://crates.io/crates/leaf) [![License](https://img.shields.io/crates/l/leaf.svg)](LICENSE)
 
-*A modular, fast and open Deep Learning Framework for distributed
-state of the art Deep Learning on both {C, G}PUs*
-
-For more information see the [Documentation](http://autumnai.github.io/leaf).
+## Introduction
+
+Leaf is a open source framework for machine intelligence, sharing concepts from
+[TensorFlow][tensorflow] and [Caffe][caffe].
+
+Leaf was started at [Autumn][autumn] to bridge the gap between research and
+production of deep learning networks. Leaf is written in [Rust][rust], a
+language which is well suited for state-of-the-art machine learning. It allows
+for performance, memory-security and extensibility, that other frameworks
+(TensorFlow, Caffe, Theano) only gain by combining high-level languages (Python)
+with low-level languages (C, C++).
+
+The architecture of Leaf's network is composed of layers, which represent
+operations over n-dimensional numerical inputs into the network, known as Blobs.
+This expressive and highly modular architecture, allows you to deploy and
+distribute your network over multiple devices such as servers, desktops, mobile
+devices and use one or many CPUs or GPUs for computation.  
+Layers usually implement mathematical operations, but can be used for many more
+such as feeding in data, logging or returning results. You can use the layers
+that come already shipped with Leaf (e.g. Convolutional, ReLU, RNN, SVM,
+etc.) or thanks to Rust, easily extend Leaf with your own layers.
+
+Leaf strives for leading-edge performance
+([benchmarks are next][benchmarks-issue]), while providing a clear and
+expressive architecture that creates - as we hope - an innovative and active
+community around machine intelligence and fuels future research.
+
+We see Leaf as the core of constructing high-performance learning networks that
+can be distributed and extended with other libraries e.g. for reinforcement
+learning (Q-learning), visualizing and monitoring the learning of the network,
+[automated preprocessing of non-numerical data][cuticula] or scale, deploy and
+distribute your network to the cloud.
+
+For more information,
+
+* see Leafs' [Documentation][documentation] or
+* the [Q&A](#qa)
+
+[caffe]: https://github.com/BVLC/caffe
+[rust]: https://www.rust-lang.org/
+[autumn]: http://autumnai.com
+[tensorflow]: https://github.com/tensorflow/tensorflow
+[benchmarks-issue]: 
+[documentation]: http://autumnai.github.io/leaf
+
+> Disclaimer: Leaf is currently in a very early and heavy stage of development.
+> If you are experiencing any bugs that are not due to not yet implemented
+> features, feel free to create a issue.
 
 ## Getting Started
 
-**Disclaimer: Leaf is currently in a very early and heavy stage of development.
-If you are experiencing any bugs that are not due to not yet implemented features,
-feel free to create a issue.**
-
 If you're using Cargo, just add Leaf to your Cargo.toml:
 
     [dependencies]
     leaf = "0.0.1"
 
-If you're using [Cargo Edit](https://github.com/killercup/cargo-edit), you can
+If you're using [Cargo Edit][cargo-edit], you can
 call:
 
     $ cargo add leaf
 
 
+You can find examples at [Leaf Examples][leaf-examples].
+Leaf Examples provides a CLI, so you can run popular Deep Learning examples with
+Leaf right from the command line.
+
+[cargo-edit]: https://github.com/killercup/cargo-edit
+[leaf-examples]: https://github.com/autumnai/leaf-examples
+
+## Leaf Ecosystem and Extensions
+
+We design Leaf and all other crates for machine learning completely modular and
+as extensible as possible. More helpful crates you can use with Leaf:
+
+- [**Cuticula**][cuticula]: Preprocessing Framework for Machine Learning
+- [**Phloem**][phloem]: Universal CPU/GPU Data Blob for Machine Learning
+
+[cuticula]: https://github.com/autumnai/cuticula
+[phloem]: https://github.com/autumnai/phloem
+
+
 ## Contributing
 
-Want to contribute? Awesome! We have [instructions to help you get started contributing code or documentation](CONTRIBUTING.md).
+Want to contribute? Awesome! We have
+[instructions to help you get started contributing code or documentation][contributing].
 
-Leaf has a mostly real-time collaboration culture and happens here on Github and
-on the [Leaf Gitter Channels](https://gitter.im/autumnai/leaf).
+Leaf has a near real-time collaboration culture and happens here on Github and
+on the [Leaf Gitter Channels][gitter-leaf].
 You can also reach out to the Maintainers
-{[@MJ](https://twitter.com/mjhirn), [@hobofan](https://twitter.com/hobofan)}.
+{[@MJ][mj], [@hobofan][hobofan]}.
 
+[contributing]: CONTRIBUTING.md
+[gitter-leaf]: https://gitter.im/autumnai/leaf
+[mj]: https://twitter.com/mjhirn
+[hobofan]: https://twitter.com/hobofan
 
-## Examples
+## Q&A
 
-You can find examples at [Leaf Examples](https://github.com/autumnai/leaf-examples).
-Leaf Examples provides a CLI, so you can run popular Deep Learning examples with
-Leaf right from the command line.
+#### _Why Rust?_
+
+The current hardware just recently became strong enough to support real-world
+usage of machine intelligence e.g. super-human image recognition, self-driving
+cars, etc.. For taking advantage of the computational power of the underlying
+hardware from GPUs to clusters you need a low-level language that allows for
+control of memory. But to make machine intelligence widely accessible you want
+to have a high-level comfortable abstraction over the underlying hardware.
+
+Rust allows us to cross this chasm.
+Rust promises performance like C/C++ but with safe memory-control. For now we
+can use C Rust wrappers for performant libraries. But in the future Rust
+rewritten libraries will have the advantage of zero-cost safe memory control,
+that will make large, parallel learning networks over CPUs and GPUs more
+feasible and more reliable to develop. The development of these future libraries
+is already under way e.g. [Glium][glium].
+
+On the usability side, Rust offers a trait-system, that makes it easy for
+researchers and hobbyists alike to extend and work with Leaf as if Leaf would
+have been written in a higher-level language such as Ruby, Python, Java, etc.
+
+#### _Who can use Leaf?_
+
+We develop Leaf under the MIT open source license, which, paired with the easy
+access and performance, makes Leaf a first-choice option for researchers and
+developers alike.
 
+#### _Why did you open source Leaf?_
+
+We believe strongly in machine intelligence and think that it will have a major
+impact on future innovations, products and our society. At Autumn, we experienced
+a lack of common and well engineered tools for machine learning and therefore
+started to create a modular toolbox for machine learning in Rust. We hope, that
+with making our work open source, we will speed-up research and development of
+production-ready applications and make their work easier as well.
+
+#### _Who is Autumn?_
+
+Autumn is a startup working on automated decision making. Autumn was started by
+two developers MJ and Max. The startup is located in Berlin and recently
+received a pre-seed investment from Axel Springer and Plug&Play.
+
+[glium]: https://github.com/tomaka/glium
 
 ## License
 
-Leaf is released under the [MIT License](LICENSE).
+Leaf is released under the [MIT License][license].
+
+[license]: LICENSE