Skip to content

Commit

Permalink
📝 docs: Cleanup to have just one source of truth
Browse files Browse the repository at this point in the history
  • Loading branch information
@abhiabhi94
abhiabhi94 committed Mar 10, 2021
1 parent 8a3c35e commit 74f9904
Show file tree
Hide file tree
Showing 5 changed files with 49 additions and 224 deletions.
6 changes: 4 additions & 2 deletions CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@ To start development on this project, fork this repository and follow the follow
# create a virtual environment
$ python3 -m venv venv
# activate the virtual environment
$ source venv/bin/activate
# activate the virtual environment(unix users)
$ . venv/bin/activate
# activate the virtual environment(window users)
$ venv\Scripts\Activate
# install dependencies
(venv) $ pip install -e . -r testapp/requirements.txt
# migrate the migrations to the database
Expand Down
17 changes: 10 additions & 7 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ django-flag-app
:alt: licence


A pluggable django application that adds the ability for users to flag(or report) your models.
A pluggable django application that adds the ability for users to flag(report or moderate) your models.


.. image:: https://github.com/abhiabhi94/django-flag-app/blob/main/docs/_static/images/django-flag-app.gif
.. image:: https://raw.githubusercontent.com/abhiabhi94/django-flag-app/main/docs/_static/images/django-flag-app.gif
:alt: flagging-process


Expand Down Expand Up @@ -96,15 +96,15 @@ Migrate

Run the migrations to add the new models to your database:

.. code:: python
.. code:: sh
python manage.py migrate flag
Connect the flag model with the target model
`````````````````````````````````````````````

In ``models.py`` add the field **flags** as a ``GenericRelation`` field to the required 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:

Expand All @@ -122,6 +122,11 @@ E.g. for a ``Post`` model, you may add the field as shown below:
# the field name should be flags
flags = GenericRelation(Flag)
.. important::


the name of the field should be **flags**.


Use template tag
`````````````````
Expand All @@ -146,6 +151,4 @@ To render the ``flag`` form for a the instance ``post``, place this inside your
Contributing
------------

Please see the instructions at `Contributing`_.

.. _Contributing: https://github.com/abhiabhi94/django-flag-app/blob/main/CONTRIBUTING.rst
Please see the instructions at :ref:`Contributing to Django Flag App`.
49 changes: 1 addition & 48 deletions docs/contributing.rst
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1 @@
===============================
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
.. include:: ../CONTRIBUTING.rst
138 changes: 1 addition & 137 deletions docs/introduction.rst
View file
Original file line number Diff line number Diff line change
@@ -1,137 +1 @@
django-flag-app
===============

.. image:: https://travis-ci.org/abhiabhi94/django-flag-app.svg?branch=main
: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

.. image:: https://badge.fury.io/py/django-flag-app.svg
:target: https://pypi.org/project/django-flag-app/
:alt: Latest PyPi version

.. image:: https://img.shields.io/pypi/pyversions/django-flag-app.svg
:target: https://pypi.python.org/pypi/django-flag-app/
:alt: python

.. image:: https://img.shields.io/pypi/djversions/django-flag-app.svg
:target: https://pypi.python.org/pypi/django-flag-app/
:alt: django

.. image:: https://readthedocs.org/projects/django-flag-app/badge/?version=latest
:target: https://django-flag-app.readthedocs.io/?badge=latest
:alt: docs

.. image:: https://img.shields.io/github/license/abhiabhi94/django-flag-app?color=gr
:target: https://github.com/abhiabhi94/django-flag-app/blob/main/LICENSE
:alt: licence

A pluggable django application that adds the ability for users to flag(or report) your models.

.. image:: ./_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',
...
)
Add URL
````````

In your root ``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
...
)
Migrate
````````

Run the migrations to add the new models to your database:

.. code:: sh
python manage.py migrate flag
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)
Use template tag
`````````````````

If you want to use web API, this step is not required. See further instructions at :ref:`API Actions`.

``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 :ref:`Contributing to Django Flag App`.
.. include:: ../README.rst
63 changes: 33 additions & 30 deletions testapp/post/management/commands/create_initial_data.py
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,42 @@
from django.contrib.auth.models import User, Group
from django.core.management.base import BaseCommand
from django.utils.translation import gettext_lazy as _

from testapp.post.models import Post


class Command(BaseCommand):
help = "Generate initial data"
help = _("Generate initial data")

@staticmethod
def __get_or_create(username, password):
created = False
try:
user = User.objects.get(username=username)
except User.DoesNotExist:
user = User.objects.create_user(username=username, password=password)
created = True
return user, created

def __generate_initial_data(self):
moderator, created = self.__get_or_create('moderator', password='moderator')
if created:
moderator_group, _ = Group.objects.get_or_create(name='flag_moderator')
moderator_group.user_set.add(moderator)

user, __ = self.__get_or_create('test', password='test')
admin_user, created_super_user = self.__get_or_create('admin', password='admin')
if created_super_user:
admin_user.is_staff = True
admin_user.save()

try:
Post.objects.get(title='Test Post')
self.stdout.write(self.style.WARNING('Initial data already present.'))

except Post.DoesNotExist:
Post.objects.create(title='Test Post', body='Hello django flag app', user=user)
self.stdout.write(self.style.SUCCESS('Initial data created successfully.'))

def handle(self, *args, **options):
generate_initial_data()


def get_or_create(username, password):
created = False
try:
user = User.objects.get(username=username)
except User.DoesNotExist:
user = User.objects.create_user(username=username, password=password)
created = True
return user, created


def generate_initial_data():
moderator, created = get_or_create('moderator', password='moderator')
if created:
moderator_group, _ = Group.objects.get_or_create(name='flag_moderator')
moderator_group.user_set.add(moderator)

user, _ = get_or_create('test', password='test')
admin_user, created_super_user = get_or_create('admin', password='admin')
if created_super_user:
admin_user.is_staff = True
admin_user.save()

try:
Post.objects.get(title='Test Post')
except Post.DoesNotExist:
Post.objects.create(title='Test Post', body='Hello django flag app', user=user)
self.__generate_initial_data()

0 comments on commit 74f9904

Please sign in to comment.