Merge pull request #9 from luizalabs/docs

Setup docs with mkdocs

docs/backend_pool.md

@@ -0,0 +1,23 @@
+Backend Pool
+============
+
+The `BackendPool` is the component which locates and instantiates your _backend_
+classes. In orther to use it you should subclass it and set a `backend_type`.
+(see [the example](/#example))
+
+`BackendPool` class
+-------------------
+
+### `get`
+
+Returns returns an instance of the backend which has the given `backend_id`
+
+#### arguments
+
+`backend_id` - The `id` of the backend you are looking for
+
+
+### `all`
+
+Returns a list of instances of all backends configured with the pool's backend
+type

docs/index.md

@@ -0,0 +1,99 @@
+Ramos - Generic Backend Pool
+============================
+
+**Ramos** is a library to create, locate, instantiate and control the lifecyle of
+generic _backends_.
+
+
+What is a backend?
+------------------
+
+_Plugable Backend_ (or _backend_ for short) is a term [borrowed from Django](http://charlesleifer.com/blog/django-patterns-pluggable-backends/).
+It is a standard interface to a resource, so that it can be _plugged_ at the
+your will. In order to instantiate a backend, **Ramos** requires the class to
+have a _classmethod_ `create`, which can't accept any parameter and must return
+your backend's instance. **Ramos** does not verify if the classes configured
+in a backend type really have a common interface, it is up to you
+(but you can use [Abstract Base Classes](https://docs.python.org/3/library/abc.html)
+for that).
+
+
+Installation
+------------
+
+install using `pip`.
+```
+pip install ramos
+```
+
+Example
+-------
+
+This is a quick step-by-step example of what you can do with **Ramos**. We will
+create 2 simple and interchangeable backends which only print a greeting.
+
+Create the backends.
+```python
+class PrintHiBackend:
+
+    id = 'hi'
+
+    @classmethod
+    def create(cls):
+        return cls()
+
+    def print(self):
+        print('hi')
+
+
+class PrintByeBackend:
+
+    id = 'bye'
+
+    @classmethod
+    def create(cls):
+        return cls()
+
+    def print(self):
+        print('bye')
+```
+
+Setup the path for your backends.
+```python
+import ramos
+
+ramos.configure(pools={
+    'print': (
+        '__main__.PrintHiBackend',
+        '__main__.PrintByeBackend',
+    )
+})
+```
+
+Setup the backend pool to load your backends.
+```python
+from ramos.pool import BackendPool
+
+class PrintBackendPool(BackendPool):
+    backend_type = 'print'
+```
+
+Instantiate the pool and use your backends!
+```python
+pool = PrintBackendPool()
+
+# iterate over all of them
+for backend in pool.all():
+    backend.print()
+
+# get a backend by id
+backend = pool.get('bye')
+backend.print()
+```
+
+See also
+--------
+
+* [Mixins](mixins)
+* [Backend Pool](backend_pool)
+* [Settings](settings)

docs/mixins.md

@@ -0,0 +1,42 @@
+Mixins
+======
+
+As every backend needs a way to create itself, the `ramos.mixins` module
+provides mixin classes for this task which might be repetitive otherwise.
+
+Usage
+-----
+
+```python
+class BaseBackend:
+
+    def do_something(self):
+        pass
+
+
+class MyBackend(SingletonCreateMixin, BaseBackend):
+
+    def do_something(self):
+        # do something else
+        pass
+
+
+backend = MyBackend.create()
+other = MyBackend.create()
+
+assert backend is other  # True
+```
+
+
+SingletonCreateMixin
+--------------------
+
+Then inherited class will return always the same instance of the backend in
+every call of `create`.
+
+
+ThreadSafeCreateMixin
+---------------------
+
+The inherited class will return a new instance of itself in every call of
+`create`.

docs/settings.md

@@ -0,0 +1,56 @@
+Settings
+--------
+
+In orther to locate backends, **Ramos** needs to know where to look for
+and which pools can use which classes.
+
+
+`ramos.configure`
+-----------------
+
+Out-of-the-box **Ramos** can use the `configure` method to setup the
+path and type of all backends available.
+
+#### arguments
+
+`pools` - A dictionary with the backend type as a key and a list of
+available backend paths as value. The list of backends given will be
+available for the [BackendPool][backend_pool] with the `backend_type`
+given in the key.
+
+#### example
+
+```python
+import ramos
+
+ramos.configure(pools={
+    'print': [
+        'path.to.backend_a',
+        'path.to.backend_b',
+    ]
+})
+```
+
+Django Settings
+---------------
+
+If you are using [Django][https://www.djangoproject.com/], you can use a
+variable `POLL_OF_RAMOS` in your settings file instead of `ramos.configure`.
+
+#### example
+```python
+# settings.py
+
+POOL_OF_RAMOS = {
+    'backend_type': [
+        'path.to.backend_a',
+        'path.to.backend_b',
+    ]
+}
+```
+
+Simple Settings
+---------------
+
+**Ramos** also supports [Simple Settings](https://github.com/drgarcia1986/simple-settings)
+which can setup a `POLL_OF_RAMOS` variable, like Django's settings.

mkdocs.yml

@@ -0,0 +1,2 @@
+site_name: Ramos
+theme: readthedocs

requirements-dev.txt

@@ -2,6 +2,7 @@
 bumpversion==0.5.3
 flake8==3.5.0
 isort==4.3.4
+mkdocs==1.0.4
 pytest-cov==2.6.0
 pytest==3.8.2
 mock==2.0.0