From b1ae7f7288710f3aac80228846b3c81fef2fd0c6 Mon Sep 17 00:00:00 2001
From: Diego Garcia <drgarcia1986@gmail.com>
Date: Fri, 15 May 2015 01:32:55 -0300
Subject: [PATCH] project documentation

---
 README.md            | 37 +++++-------------
 docs/index.md        | 93 ++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml           |  8 ++++
 requirements-dev.txt |  1 +
 4 files changed, 111 insertions(+), 28 deletions(-)
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/README.md b/README.md
index b87fa26..300b453 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,24 @@
 Python Simple Settings
 ======================
+[![Documentation Status](https://readthedocs.org/projects/simple-settings/badge/?version=latest)](https://readthedocs.org/projects/simple-settings/?badge=latest)
 [![Code Issues](http://www.quantifiedcode.com/api/v1/project/1b5307f0f1584c3b9c736f976b57e973/badge.svg)](http://www.quantifiedcode.com/app/project/1b5307f0f1584c3b9c736f976b57e973)
 [![Build Status](https://travis-ci.org/drgarcia1986/simple-settings.svg)](https://travis-ci.org/drgarcia1986/simple-settings)
 [![Coverage Status](https://coveralls.io/repos/drgarcia1986/simple-settings/badge.svg)](https://coveralls.io/r/drgarcia1986/simple-settings)
 
 A simple way to manage your project settings.
 
-With `simple_settings` you just need specify your settings module in `--settings` arg (of command line or enviroment) and all will be available in `simple_settings.settings`.
+It is inspired by Django's settings system but is generic for any python project.
+With `simple-settings` you just need specify your settings module in `--settings` arg of command line (or `settings` of environment) and all will be available in `simple_settings.settings`.
 
-### Instalation
+**IMPORTANT**: For each variable in your settings module, simple-settings will seek it's value in environment (to override value of module).
+
+### Installation
 Use `pip` (simple like this project :smile:).
 
 ```bash
 $ pip install simple-settings
 ```
 
-### Usage
-#### _project_settings.py_
-```python
-# -*- coding: utf-8 -*-
-SIMPLE_CONF = 'simple'
-```
-#### _app.py_
-```python
-# -*- coding: utf-8 -*-
-from simple_settings import settings
-
-print settings.SIMPLE_CONF
-```
-#### _Run_
-With command line args
-```bash
-$ python app.py --settings=project_settings
-simple
-```
-Or env
-```bash
-$ export settings=project_settings
-$ python app.py
-simple
-```
-Check [examples](https://github.com/drgarcia1986/simple-settings/tree/master/examples) for more usage samples.
+### Quick links
+ - [Documentation](http://simple-settings.readthedocs.org/en/latest/)
+ - [Examples](https://github.com/drgarcia1986/simple-settings/tree/master/examples)
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..2545dbf
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,93 @@
+Python Simple Settings
+======================
+A simple way to manage your project settings.
+
+It is inspired by Django's settings system but is generic for any python project.<br>
+With simple-settings you just need specify your settings module in `--settings` arg of command line (or `settings` of environment) and all settings will be available in `simple_settings.settings`.
+
+```python
+from simple_settings import settings
+
+
+print settings.FOO
+```
+
+## Installation
+simple-settings is available on [Pypi](https://pypi.python.org/pypi/simple-settings).
+
+```bash
+$ pip install simple-settings
+```
+
+## How this works
+
+simple-settings reads and stores all variables (or constants if you prefer) of a python module that you specify.
+For store your settings you need at least one python module.
+The objects in this python module, work as a mapping to settings of project, because, for each object in this module,
+simple-settings will seek it's value in environment before assuming the value presenting in module.
+
+To specify your settings module you have two approaches, with command line or environment.
+
+For example, imagine that you have a python module for your project settings and this file is in "_settings/development.py_" (a common example).
+To load settings of this file you can run your project with command line arg `--settings`:
+
+```bash
+$ python app.py --settings=settings.development
+```
+
+Or set the environment variable `settings`:
+
+```bash
+$ export settings=settings.development
+$ python app.py
+```
+The `simple_settings.settings` object reads the command line and environment in this order (but simple-settings takes first value it encounters), to know which file to load.
+
+
+## Example
+This is a very dummy example, in real world you would use simple-settings in more complex cases.
+
+### **project_settings.py**
+
+In this example we just store a simple string but any python type is accepted.
+
+```python
+SIMPLE_CONF = 'simple'
+```
+### **app.py**
+
+You don't need specify which setting _simple-settings_ must load, you can do this with command line or environment.
+
+```python
+from simple_settings import settings
+
+print settings.SIMPLE_CONF
+```
+### **Run**
+
+You can specify your settings module with command line:
+```bash
+$ python app.py --settings=project_settings
+simple
+```
+Or environment:
+```bash
+$ export settings=project_settings
+$ python app.py
+simple
+```
+### **Override settings value**
+
+You can override the values of your settings module with environment variables.
+
+```bash
+$ export SIMPLE_CONF="simple from env"
+$ python app.py --settings=project_settings
+simple from env
+```
+Check [examples](https://github.com/drgarcia1986/simple-settings/tree/master/examples), in project repository for more usage samples.
+
+## Changelog
+
+### [0.1.0] - 2015-05-14
+ - First release.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..f6fc587
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,8 @@
+site_name: Simple Settings
+site_description: A simple way to manage your project settings.
+repo_url: https://github.com/drgarcia1986/simple-settings
+site_url: http://simple-settings.readthedocs.org/en/latest/
+theme: readthedocs
+
+pages:
+    - ['index.md', 'Home']
diff --git a/requirements-dev.txt b/requirements-dev.txt
index a2befc7..0208b86 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -6,3 +6,4 @@ pytest==2.7.0
 pytest-cov==1.8.1
 bumpversion==0.5.1
 flake8==2.4.0
+mkdocs==0.12.2