Added documentation - features, installation, setup and list of all functions (#5)

Author: shirishagaddi

docs/source/commands.rst

@@ -0,0 +1,178 @@
+Commands
+===========
+
+Usage
+-------
+
+    .. code-block:: python
+
+        fab <run_local/run_stage/run_live> <command_name>
+
+
+    **List Commands** - shows the list of all available fab commands
+
+
+        .. code-block:: python
+
+            fab -l
+
+
+Install Requirements
+----------------------
+
+* To install the requirements on your local system:
+
+    .. code-block:: python
+
+        fab run_local activate_env_install_requirements
+
+                (or)
+
+        fab activate_env_install_requirements
+
+* To install the requirements on your remote staging servers:
+
+    .. code-block:: python
+
+        fab run_stage activate_env_install_requirements
+
+* To install the requirements on your remote live servers:
+
+    .. code-block:: python
+
+        fab run_live activate_env_install_requirements
+
+
+Rsync project to remote server(stage/live)
+---------------------------------------------
+
+To rsync project local files to remote destination server -
+
+    * with settings file -
+
+        .. code-block:: python
+
+            fab <run_stage/run_live> rsync_with_settings
+
+    * without settings file -
+
+        .. code-block:: python
+
+            fab <run_stage/run_live> rsync_without_settings
+
+
+Deploy To Server
+------------------
+
+This commands copy local project files to destination(stage/live) servers, installs requirements, applies migrations and finally runs uWSGI server(both in debug and deployment modes)
+
+    .. code-block:: python
+
+            fab <run_stage/run_live> deploy_to_server
+
+    By default, this command rsyncs project files without settings file and runs touch command for project uwsgi file under /etc/uwsgi/vassals/ folder.
+
+    * To rsync with settings file and to run uwsgi in debug mode:
+
+        .. code-block:: python
+
+            fab <run_stage/run_live> deploy_to_server:sync_with_setting='true',debug='true'
+
+
+    .. note::
+
+        It automatically creates project_root, env in server if not exists
+
+
+Local database backup
+-----------------------
+
+    .. code-block:: python
+
+        fab take_local_backup
+
+
+Server database backup
+------------------------
+
+    .. code-block:: python
+
+        fab <run_stage/run_live> take_server_backup
+
+
+Restore Server database to Local
+---------------------------------
+
+.. code-block:: python
+
+        fab <run_stage/run_live> take_server_backup
+        fab restore_to_local
+
+
+Reset Local database
+-----------------------
+
+    .. code-block:: python
+
+        fab reset_local_db
+
+
+Reset Server database
+-----------------------
+
+    .. code-block:: python
+
+        fab <run_stage/run_live> reset_server_db
+
+
+Run Management Commands
+--------------------------
+
+This function is used to run management commands -
+
+    .. code-block:: python
+
+            fab <run_local/run_stage/run_live> manage_py:<management_command_name>
+
+    * To apply migrations
+
+        .. code-block:: python
+
+                fab <run_local/run_stage/run_live> migrate
+
+    * Execute collect static
+
+        .. code-block:: python
+
+                fab <run_local/run_stage/run_live> collect_static
+
+    * Rebuild search index
+
+        .. code-block:: python
+
+                fab <run_local/run_stage/run_live> rebuild_index
+
+    * To restart celery in remote servers
+
+        .. code-block:: python
+
+                fab <run_stage/run_live> restart_celery
+
+    * To restart supervisorctl in remote servers
+
+        .. code-block:: python
+
+                fab <run_stage/run_live> restart_supervisior
+
+    * To restart uwsgi in remote servers
+
+        .. code-block:: python
+
+                fab <run_stage/run_live> restart_uwsgi
+
+    * To restart remote servers
+
+        .. code-block:: python
+
+                fab <run_stage/run_live> restart_server
+

docs/source/conf.py

@@ -119,7 +119,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/configuration.rst

@@ -0,0 +1,21 @@
+Setup
+=========
+
+* First, create an YAML file similar to `sample_config.yaml`_ and fill the configuration details.
+
+* Next, create a file named :code:`fabfile.py` in your project directory and import all functions(fab commands/tasks) from `django_spanner`.
+
+* Finally, call the :code:`setup()` function with your configuration yaml file path.
+
+
+**Here is an example fabfile**  -
+
+.. code-block:: python
+
+    # fabfile.py
+    from django_spanner.commands import *
+    setup("config_file_name.yaml")
+
+
+.. _`sample_config.yaml`: https://github.com/MicroPyramid/django-spanner/blob/master/django_spanner/sample_config.yaml
+

docs/source/features.rst

@@ -0,0 +1,19 @@
+Features
+===========
+
+    * Install requirements in a virtualenv.
+    * Migrate database.
+    * Execute any management command.
+    * Rsync files to destination server(stage/live) with and without settings file.
+    * Deploy the django application to server(Installs requirements, migrates database, rsync files, runs uwsgi server).
+    * Take database backups(server backups as well as local).
+    * Restore local and server databases.
+    * Reset local and server databases.
+    * Restart server, celery, supervisor, uwsgi.
+    * Rebuild index, collect static.
+
+
+.. note::
+
+    You can execute all these commands in local as well as remote servers.
+

docs/source/index.rst

@@ -3,20 +3,49 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to django_spanner's documentation!
-==========================================
 
-Contents:
+Django Spanner
+================
+
+Django Spanner is a simple package used to deploy and manage `Django`_ applications. Django Spanner is a set of commands used to deploy and manage django projects. It internally uses `Fabric`_. This can also be called as **Deploying Django with Fabric**.
+
+* You can use this to deploy & manage any django application with just few configurations. Configure once and run many times.
+
+* As well as you can deploy & manage single django application on multiple remote servers (multiple staging servers, multiple live servers). You can specify different configuration for each type of server (stage/live) like here `sample config file`_
+
+* Also used to manage local django project to install requirements, run make migrations, migrate, take database backups and many more...
+
+
+This package is developed by `MicroPyramid`_ team. Please refer the `github repository`_ for the django-spanner source code. It's free and open source.
+
+
+Github Repository
+********************
+
+    Django Spanner - `https://github.com/MicroPyramid/django-spanner`_
+
+
+Contents
+----------
 
 .. toctree::
    :maxdepth: 2
 
+   features
+   installation
+   configuration
+   commands
+
+
+.. _`Django`: https://www.djangoproject.com/
+
+.. _`Fabric`: http://www.fabfile.org/
+
+.. _`MicroPyramid`: https://micropyramid.com/
 
+.. _`github repository`: https://github.com/MicroPyramid/django-spanner
 
-Indices and tables
-==================
+.. _`https://github.com/MicroPyramid/django-spanner`: https://github.com/MicroPyramid/django-spanner
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. _`sample config file`: https://github.com/MicroPyramid/django-spanner/blob/master/django_spanner/sample_config.yaml
 

docs/source/installation.rst

@@ -0,0 +1,16 @@
+Installation
+=============
+
+The recommended way to install the django-spanner into a virtualenv using pip::
+
+    pip install django-spanner
+
+
+Or, install using the latest version from GitHub::
+
+    git clone https://github.com/MicroPyramid/django-spanner.git
+
+    cd django_spanner
+
+    python setup.py install
+