Change format for documentation files to RST

CONTRIBUTING.rst

@@ -0,0 +1,48 @@
+===============================
+Contributing to Django Flag App
+===============================
+
+There are many ways to contribute to the project. You may improve the documentation, address a bug, add some feature to the code or do something else. All sort of contributions are welcome.
+
+
+Development
+-----------
+
+To start development on this project, fork this repository and follow the following instructions.
+
+.. code:: sh
+
+    # clone the forked repository
+    $ git clone YOUR_FORKED_REPO_URL
+
+    # create a virtual environment
+    $ python3 -m venv venv
+    # activate the virtual environment
+    $ source venv/bin/activate
+    # install dependencies
+    (venv) $ pip install -e . -r testapp/requirements.txt
+    # migrate the migrations to the database
+    (venv) $ python manage.py migrate
+    # create data
+    (venv) $ python manage.py create_initial_data
+    # start the development server
+    (venv) $ python manage.py runserver
+
+
+Testing
+-------
+
+To run tests against a particular ``python`` and ``django`` version installed inside your virtual environment, you may use:
+
+.. code:: sh
+
+    (venv) $ python manage.py test
+
+To run tests against all supported ``python`` and ``django`` versions, you may run:
+
+.. code:: sh
+
+    # install dependency
+    (venv) $ pip install tox
+    # run tests
+    (venv) $ tox

README.rst

@@ -0,0 +1,121 @@
+===============
+django-flag-app
+===============
+
+.. image:: https://img.shields.io/github/license/abhiabhi94/django-flag-app?color=gr
+    :target: https://github.com/abhiabhi94/django-flag-app/blob/master/LICENSE
+    :alt: licence
+
+.. image:: https://travis-ci.org/abhiabhi94/django-flag-app.svg?branch=master
+    :target: https://travis-ci.org/abhiabhi94/django-flag-app
+    :alt: build
+
+.. image:: https://coveralls.io/repos/github/abhiabhi94/django-flag-app/badge.svg
+    :target: https://coveralls.io/github/abhiabhi94/django-flag-app
+    :alt: coverage
+
+A pluggable django application to add flagging to your models.
+
+.. image:: ./docs/_static/images/django-flag-app.gif
+    :alt: flagging-process
+
+Installation
+------------
+
+Install using ``pip``
+
+.. code:: sh
+
+    $ pip install django-flag-app
+
+If you want, you may install it from the source, grab the source code and run ``setup.py``.
+
+.. code:: sh
+
+    $ git clone git://github.com/abhiabhi94/django-flag-app.git
+    $ cd django-flag-app
+    $ python setup.py install
+
+Usage
+-----
+
+* Add app
+
+To enable ``django_flag_app`` in your project you need to add it to ``INSTALLED_APPS`` in your projects ``settings.py`` file:
+
+.. code:: python
+
+    INSTALLED_APPS = (
+        ...
+        'flag',
+        ...
+    )
+
+Step-1: Add url
+````````````````
+
+In ``urls.py``:
+
+.. code:: python
+
+    urlpatterns = patterns(
+            path('admin/', admin.site.urls),
+            path('flag/', include('flag.urls')),
+            ...
+            path('api/', include('flag.api.urls')),  # only required for API Framework
+            ...
+        )
+
+Step 2: Migrate
+````````````````
+
+Run the migrations to add the new models to your database:
+
+.. code:: python
+
+    python manage.py migrate flag
+
+
+Step 3: Connect the flag model with the target model
+`````````````````````````````````````````````````````
+
+In ``models.py`` add the field **flags** as a ``GenericRelation`` field to the required model.
+
+E.g. for a ``Post`` model, you may add the field as shown below:
+
+.. code:: python
+
+    from django.contrib.contenttypes.fields import GenericRelation
+
+    from flag.models import Flag
+
+
+    class Post(models.Model):
+        user = models.ForeignKey(User)
+        title = models.CharField(max_length=200)
+        body = models.TextField()
+        # the field name should be flags
+        flags = GenericRelation(Flag)
+
+
+Step 4: Use template tag
+`````````````````````````
+
+``render_flag_form`` tag requires 2 required positional arguments:
+
+    1. Instance of the targeted model.
+    2. User object.
+
+To render the ``flag`` form for a the instance ``post``, place this inside your detail view, perhaps in some template of the sort ``postdetail.html``.
+
+.. code:: jinja
+
+    {% render_flag_form post user %}
+
+
+Contributing
+------------
+
+Please see the instructions at `Contributing`_.
+
+.. _Contributing: ./CONTRIBUTING.rst

setup.py

@@ -1,14 +1,18 @@
+import os
 import setuptools
 
 
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
 def get_description():
-    with open('README.md', 'r') as fh:
+    with open(os.path.join(BASE_DIR, 'README.rst')) as fh:
         description = fh.read().strip()
     return description
 
 
 def get_version():
-    with open('VERSION', 'r') as version_file:
+    with open(os.path.join(BASE_DIR, 'VERSION')) as version_file:
         version = version_file.read().strip()
     return version