user_documentation (#22)

* Tide up contribution page

* Change base snippet to be wblock instead of block

* Add snippet for main function

* Rename winside_block to inside_wblock

* Change forin definition

* Fix switch case

* Write getting started page

* move snippet library in separate file and add names to snippet examples

* remove under development comment in docs

* replaced README.md with README.rst

* Add short description and example

* Fix bad indent

* Add link to documentation

* Fix docs link

* Changed getting started a bit

* Add link to getting started section

README.rst

@@ -0,0 +1,35 @@
+########
+Homotopy
+########
+
+.. image:: https://travis-ci.org/Ahhhhmed/homotopy.svg?branch=master
+    :target: https://travis-ci.org/Ahhhhmed/homotopy
+.. image:: https://readthedocs.org/projects/homotopy/badge/?version=latest
+    :target: http://homotopy.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+.. image:: https://codecov.io/gh/Ahhhhmed/homotopy/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/Ahhhhmed/homotopy
+
+Homotopy is a snippet compiler.
+Instead of expanding and filling the blanks it lets you finish your thought and get the result you are expecting.
+
+Write that complex thought in one line and let
+Homotopy take care of parentheses, formatting, indent and all that boring stuff.
+
+.. code-block:: text
+
+    for#int$i%0%5>printf("Hello, five times.");
+
+.. code-block:: C++
+
+   for(int i=0; i<5; i++){
+        printf("Hello, five times.");
+   }
+
+---------------
+Getting started
+---------------
+
+See `getting started`_ section in documentation.
+
+.. _getting started: http://homotopy.readthedocs.io/en/latest/getting_started.html

docs/contributing.rst

@@ -40,13 +40,13 @@ The code is separated in several components:
 * `Syntax tree`_
 * `Snippet provider`_
 * `Compiler`_
-* `Utilities`_
 * `Application frontend`_
 
 Preprocessor
 ^^^^^^^^^^^^
 
 Before parsing and creating syntax tree some prepossessing is done to enable some feathers.
+They are described in following sections.
 
 Decorators
 """"""""""
@@ -84,6 +84,23 @@ writing that text and expanding the snippet afterwords.*
 To enable this preprocessor appends :code:`&[{cursor_marker}]` to the snippet text
 so a plugin can put cursor at the marker location.
 
+Usage
+"""""
+
+.. autoclass:: homotopy.preprocessor.Preprocessor
+    :members: expand_decorators, put_cursor_marker
+    :member-order: bysource
+
+.. code-block:: python
+
+    from homotopy.preprocessor import Preprocessor
+    from homotopy.snippet_provider import SnippetProvider
+
+    preprocessor = Preprocessor(SnippetProvider('python', ['folder1', 'folder2']))
+    snippet = "for"
+    expanded_snippet = preprocessor.expand_decorators(snippet)
+    expanded_snippet_with_cursor = preprocessor.put_cursor_marker(expanded_snippet)
+
 Parser
 ^^^^^^
 
@@ -170,8 +187,22 @@ Escape sequence
 """""""""""""""
 
 Homotopy uses escape sequence to enable operator usage in snippets.
-Character after :code:`\` will always be a part of snippet and not recognised as an operator.
+Character after :code:`'\'` will always be a part of snippet and not recognised as an operator.
 
+Usage
+"""""
+
+.. autoclass:: homotopy.parser.Parser
+    :members: parse
+    :member-order: bysource
+
+.. code-block:: python
+
+    from homotopy.parser import Parser
+
+    parser = Parser()
+    snippet = "for"
+    syntax_tree = parser.parse(snippet)
 
 Syntax tree
 ^^^^^^^^^^^
@@ -181,6 +212,16 @@ Tree structure of a snippet.
 .. automodule:: homotopy.syntax_tree
     :members:
 
+Usage
+"""""
+
+.. code-block:: python
+
+    from homotopy.syntax_tree import SimpleSnippet, CompositeSnippet
+
+    simple_snippet = SimpleSnippet("for")
+    composite_snippet = CompositeSnippet(simple_snippet, '>', SimpleSnippet('code'))
+
 Snippet provider
 ^^^^^^^^^^^^^^^^
 
@@ -201,27 +242,24 @@ Snippets definition are writen in json files as shown is the following example.
 Note that language can be a string or a list of strings. Use :code:`all` for snippets that should always be included.
 Language can be excluded by prefixing it with :code:`~` (for example :code:`~c++`).
 
-Implementation
-""""""""""""""
-
 Snippet provider reads all the files containing snippets.
 It searches all json files contained in the given list of folders files.
 The list of folders is specified in the :code:`path` variable (similar to :code:`os.path`).
 
-.. autoclass:: homotopy.snippet_provider.SnippetProvider
-    :members: __getitem__, __init__
-    :member-order: bysource
-
 Usage
 """""
 
-Using this class should be straightforward. Look.
+.. autoclass:: homotopy.snippet_provider.SnippetProvider
+    :members: __getitem__, __init__
+    :member-order: bysource
 
 .. code-block:: python
 
+    from homotopy.snippet_provider import SnippetProvider
+
     provider = SnippetProvider("C++", ["folder1", "folder2"])
     snippet = "for"
-    snippetExpansion = provider[snippet] # snippetExpansion == "for(###){$$$}" if used with json from above
+    snippetExpansion = provider[snippet]
 
 Compiler
 ^^^^^^^^
@@ -298,10 +336,30 @@ Accessing outer parameters can be done in the following way:
 The snippet above would create a public empty constructor. :code:`{{?###}}` binds to the same value as :code:`{{?###}}`
 from the snippet above the current one.
 
-Utilities
-^^^^^^^^^
+Usage
+"""""
+
+.. autoclass:: homotopy.compiler.Compiler
+    :members: compile
+    :member-order: bysource
+
+.. code-block:: python
+
+    from homotopy.compiler import Compiler
+    from homotopy.parser import Parser
+    from homotopy.snippet_provider import SnippetProvider
+    from homotopy.util import IndentManager
+
+    snippet_provider = SnippetProvider('python', ['folder1', 'folder2'])
+    indent_manager = IndentManager(snippet_provider)
+
+    compiler = Compiler(snippet_provider, indent_manager)
+    parser = Parser()
+
+    snippet = "for>code"
+    syntax_tree = parser.parse(snippet)
 
-Utility functionality to help the development of editor add-ons.
+    compiled_snippet = compiler.compile(syntax_tree)
 
 Application frontend
 ^^^^^^^^^^^^^^^^^^^^