Commits

Artur Barseghyan committed de5dbf1 Draft

updated docs and the automated demo installer

  • Participants
  • Parent commits d878d71

Comments (0)

Files changed (6)

 (https://github.com/barseghyanartur/django-werewolf/tree/stable/example) and read the `readme.rst` of the `news`
 app.
 
+Imaginary app concept
+-----------------------------------
+In short, our imaginary wpuld work as follows.
+
+- Chief Editors creates News items and assign those to Writers and Editors.
+- Once a News item has been created, both Writer and the Editor assigned do get an e-mail notification about
+  the fact that a News item has been assigned to them.
+- Writer is supposed to fill the assigned News item with content and once the News item is ready, change
+  its' status to `ready`.
+- The assigned Editor would get an e-mail notification about the fact that the News item has been changed to
+  `ready`.
+- The assigned Editor is supposed to check the News item  with status `ready` and if it's acceptable, change
+  the News item status to `reviewed`.
+- Once a News item status has been set to `reviewed`, the assigned Writer can no longer access it in the admin.
+- The assigned Chief Editor would get an e-mail notification about the fact that the News item has been changed
+  to `reviewed.`
+- The assigned Chief Editor is supposed to check the News item with status `reviewed` and if it acceptable, 
+  change the News item status to `published`.
+- Once a News item status has been set to `published`, the assigned Editor can no longer access it in the admin.
+- Once a News item status has been changed to `published`, all Chief Editors in the system, as well as the
+  assigned Writer and Editor get an e-mail notification about the fact that the News item has been published.
+
+Automated example installer
+-----------------------------------
+In order to be able to quickly evaluate the django-werewolf, an automated installer demo has been created as
+well (Debian only). Follow the instructions below for having the demo running within a minute.
+
+Grab the latest `django-werewolf-example-app-install.sh`
+
+    $ wget https://raw.github.com/barseghyanartur/django-werewolf/stable/django-werewolf-example-app-install.sh
+
+Create a new- or switch to existing- virtual environement, assign execute rights to the installer and run
+the `django-werewolf-example-app-install.sh`.
+
+    $ chmod +x django-werewolf-example-app-install.sh
+
+    $ ./django-werewolf-example-app-install.sh
+
+You can now go to the backend and test the app.
+
+- URL: http://127.0.0.1:8000/admin/news/newsitem/
+- Admin username: admin
+- Password: test
+- Chief Editor username: chief_editor
+- Chief Editor password: test
+- Editor username: editor
+- Editor password: test
+- Writer username: writer
+- Writer password: test
+
+Let's now step-by-step review our imaginary example app.
+
 settings.py
 ----------------------------------
 >>> # Workflow statuses; order is preserved.

File django-werewolf-example-app-install.sh

 mkdir ../static/
 mkdir ../db/
 cp local_settings.example local_settings.py
-./manage.py syncdb --noinput
-./manage.py collectstatic --noinput
-./manage.py runserver
+./manage.py syncdb --noinput --traceback -v 3
+./manage.py collectstatic --noinput --traceback -v 3
+./manage.py runserver --traceback -v 3

File docs/index.rst

 ==================================
 Item publishing workflow for Django (fully integrated into Django admin).
 
+Prerequisites
+===================================
+- Django 1.5.+
+- Python 2.7.+, 3.3.+
+
 Installation
 ==================================
 1. Install django-werewolf into your virtual environment:
 ==================================
 It's all about item publishing in a workflow. We have various `intermediate` statuses (work in-progress) and a
 final `status` which means that the item is actually published. Some users should be able to set the item status
-to `published`, some others not. This app allows you (and gives you a good working example with pre-configured django
-environment) to write a custom workflow for publishing your items with minimal efforts.
+to `published`, some others not. This app allows you (and gives you a good working example with pre-configured
+Django environment) to write a custom workflow for publishing your items with minimal efforts.
 
-For a complete example of a working django-werewolf app see the https://bitbucket.org/barseghyanartur/django-werewolf
-(example directory) and read the `readme.rst` of the `news` app.
+For a complete example of a working django-werewolf app see the
+(https://github.com/barseghyanartur/django-werewolf/tree/stable/example) and read the `readme.rst` of the `news`
+app.
+
+Imaginary app concept
+-----------------------------------
+In short, our imaginary wpuld work as follows.
+
+- Chief Editors creates News items and assign those to Writers and Editors.
+- Once a News item has been created, both Writer and the Editor assigned do get an e-mail notification about
+  the fact that a News item has been assigned to them.
+- Writer is supposed to fill the assigned News item with content and once the News item is ready, change
+  its' status to `ready`.
+- The assigned Editor would get an e-mail notification about the fact that the News item has been changed to
+  `ready`.
+- The assigned Editor is supposed to check the News item  with status `ready` and if it's acceptable, change
+  the News item status to `reviewed`.
+- Once a News item status has been set to `reviewed`, the assigned Writer can no longer access it in the admin.
+- The assigned Chief Editor would get an e-mail notification about the fact that the News item has been changed
+  to `reviewed.`
+- The assigned Chief Editor is supposed to check the News item with status `reviewed` and if it acceptable,
+  change the News item status to `published`.
+- Once a News item status has been set to `published`, the assigned Editor can no longer access it in the admin.
+- Once a News item status has been changed to `published`, all Chief Editors in the system, as well as the
+  assigned Writer and Editor get an e-mail notification about the fact that the News item has been published.
+
+Automated example installer
+-----------------------------------
+In order to be able to quickly evaluate the django-werewolf, an automated installer demo has been created as
+well (Debian only). Follow the instructions below for having the demo running within a minute.
+
+Grab the latest `django-werewolf-example-app-install.sh`
+
+    $ wget https://raw.github.com/barseghyanartur/django-werewolf/stable/django-werewolf-example-app-install.sh
+
+Create a new- or switch to existing- virtual environement, assign execute rights to the installer and run
+the `django-werewolf-example-app-install.sh`.
+
+    $ chmod +x django-werewolf-example-app-install.sh
+
+    $ ./django-werewolf-example-app-install.sh
+
+You can now go to the backend and test the app.
+
+- URL: http://127.0.0.1:8000/admin/news/newsitem/
+- Admin username: admin
+- Password: test
+- Chief Editor username: chief_editor
+- Chief Editor password: test
+- Editor username: editor
+- Editor password: test
+- Writer username: writer
+- Writer password: test
+
+Let's now step-by-step review our imaginary example app.
 
 settings.py
 ----------------------------------
 
 news/models.py
 ----------------------------------
-In the example below we have a basic news item model. We have Chief Editors with full access to news items, we have
-editors with less privelleges and Writers with very little privelleges. Chief Editors create articles, select an
-Editor and a Writer (both get notified) and let them work on the article. Writers can only set an article status to
-`new`, `draft` and `ready` (ready to be checked). Editors review the articles with status `ready` and set the status
-to `reviewed`. Chief Editors publish articles that are `reviewed`. Your implementation can be as custom as you want
-it. Think in Django user groups (``django.contrib.auth.models.Group``) and Django permissions system.
+In the example below we have a basic news item model. We have Chief Editors with full access to news items, we
+have editors with less privelleges and Writers with very little privelleges. Chief Editors create articles,
+select an Editor and a Writer (both get notified) and let them work on the article. Writers can only set an
+article status to `new`, `draft` and `ready` (ready to be checked). Editors review the articles with status
+`ready` and set the status to `reviewed`. Chief Editors publish articles that are `reviewed`. Your
+implementation can be as custom as you want it. Think in Django user groups (``django.contrib.auth.models.Group``)
+and Django permissions system.
 
 NOTE: See the `Permission tuning` section.
 
 >>> class NewsItem(WerewolfBaseModel): # Important!
 >>>     title = models.CharField(_("Title"), max_length=100)
 >>>     body = models.TextField(_("Body"))
->>>     date_published = models.DateTimeField(_("Date published"), default=datetime.datetime.now())
->>>     author = models.ForeignKey(User, verbose_name=_("Author"), related_name='authors', limit_choices_to=_writers)
->>>     editor = models.ForeignKey(User, verbose_name=_("Editor"), related_name='editors', limit_choices_to=_editors)
->>>     chief_editor = models.ForeignKey(User, verbose_name=_("Chief editor"), related_name='chief_editors', \
+>>>     date_published = models.DateTimeField(_("Date published"), \
+>>>                                           default=datetime.datetime.now())
+>>>     author = models.ForeignKey(User, verbose_name=_("Author"), related_name='authors', \
+>>>                                limit_choices_to=_writers)
+>>>     editor = models.ForeignKey(User, verbose_name=_("Editor"), related_name='editors', \
+>>>                                limit_choices_to=_editors)
+>>>     chief_editor = models.ForeignKey(User, verbose_name=_("Chief editor"), \
+>>>                                      related_name='chief_editors', \
 >>>                                      limit_choices_to=_chief_editors)
 >>>
 >>>     class Meta(WerewolfBaseMeta): # Important!
 >>>         verbose_name = "News item"
 >>>         verbose_name_plural = "News items"
 
-Or if you want to define custom permissions for your model as well, do extend the werewolf permissions as follows:
+Or if you want to define custom permissions for your model as well, do extend the werewolf permissions as
+follows:
 
 >>> from werewolf.models import WerewolfBaseModel
 >>> from werewolf.utils import extend_werewolf_permissions
 >>>
 >>> admin.site.register(NewsItem, NewsItemAdmin)
 
-NOTE: If you override the ``queryset`` method of your model's admin class, make sure to see the source code of
-`werewolf.admin.WerewolfBaseAdmin.queryset` and copy the approach from there. Otherwise, your users with no permission
-to change the `published` status will be able to chgange the status of already published items to non-published
-statuses.
+NOTE: If you override the ``queryset`` method of your model's admin class, make sure to see the source code
+of `werewolf.admin.WerewolfBaseAdmin.queryset` and copy the approach from there. Otherwise, your users with
+no permission to change the `published` status will be able to chgange the status of already published items
+to non-published statuses.
 
 news/views.py
 ----------------------------------
 
 news/werewolf_triggers.py
 ----------------------------------
-In order to perform extra tasks on status change, triggers are used. You simply make a new file in your app called
-`werewolf_triggers.py` and define custom classes that should be called when a ``status`` field of your model changes
-to a certain value. Each trigger should subclass the ``werewolf.triggers.WerewolfBaseTrigger`` class.
+In order to perform extra tasks on status change, triggers are used. You simply make a new file in your app
+called `werewolf_triggers.py` and define custom classes that should be called when a ``status`` field of your
+model changes to a certain value. Each trigger should subclass the ``werewolf.triggers.WerewolfBaseTrigger``
+class.
 
 >>> from werewolf.triggers import WerewolfBaseTrigger, registry
 >>>
     - editor: Belongs to group `Editors`.
     - writer: Belongs to group `Writers`.
 
-4. Now log into the admin with different user and see your admin for the `News item` (created items with `chiefeditor`
-   account, then view them with `editor` and `writer`.
+4. Now log into the admin with different user and see your admin for the `News item` (created items with
+   `chiefeditor` account, then view them with `editor` and `writer`.
 
-That's it. If somehow you don't see the new permissions (`Can change status to draft`, `Can change status to new`, etc)
-run a management command `syncww`:
+That's it. If somehow you don't see the new permissions (`Can change status to draft`,
+`Can change status to new`, etc) run a management command `syncww`:
 
     $ ./manage.py syncww
 
 Running the example project
 ==================================
-A working example of a django-werewolf app is available here: https://bitbucket.org/barseghyanartur/django-werewolf
-(see the `example` directory).
+A working example of a django-werewolf app is available here:
+https://github.com/barseghyanartur/django-werewolf/tree/stable/example
 
 1. Go to example/example directory
 
 
     $ ./manage.py runserver
 
-License
-============
-GPL 2.0/LGPL 2.1
-
 Documentation
 ==================================
 Contents:
 * :ref:`modindex`
 * :ref:`search`
 
+License
+==================================
+GPL 2.0/LGPL 2.1
+
 Support
 ==================================
 For any issues contact me at the e-mail given in the `Author` section.

File example/fixtures/auth.group.json

-[{"pk": 1, "model": "auth.group", "fields": {"name": "Chief Editors", "permissions": [28, 36, 37, 29, 32, 31, 35, 33, 34, 30]}}, {"pk": 2, "model": "auth.group", "fields": {"name": "Editors", "permissions": [36, 29, 32, 31, 33, 34]}}, {"pk": 3, "model": "auth.group", "fields": {"name": "Writers", "permissions": [29, 32, 31, 33]}}]

File example/fixtures/auth.user.json

-[{"pk": 1, "model": "auth.user", "fields": {"username": "admin", "first_name": "", "last_name": "", "is_active": true, "is_superuser": true, "is_staff": true, "last_login": "2013-06-12T21:47:59.889Z", "groups": [], "user_permissions": [], "password": "pbkdf2_sha256$10000$9DPdA3RtmTgh$Src5o/ZXs/zJSvjducjZ8YaiBEzRvrqJOEjxEznntVE=", "email": "admin@example.com", "date_joined": "2013-06-12T19:39:35.765Z"}}, {"pk": 2, "model": "auth.user", "fields": {"username": "writer", "first_name": "Wri", "last_name": "Ter", "is_active": true, "is_superuser": false, "is_staff": true, "last_login": "2013-06-12T19:45:40.265Z", "groups": [3], "user_permissions": [], "password": "pbkdf2_sha256$10000$50IfM3w5uFv6$db2Ixz1reRlFNkaIVu0pVLitQWZFcKJ0GGNC19wmJiQ=", "email": "writer@foreverchild.info", "date_joined": "2013-06-12T19:42:22Z"}}, {"pk": 3, "model": "auth.user", "fields": {"username": "editor", "first_name": "Edi", "last_name": "Tor", "is_active": true, "is_superuser": false, "is_staff": true, "last_login": "2013-06-12T19:44:40.617Z", "groups": [2], "user_permissions": [], "password": "pbkdf2_sha256$10000$RomRe6xqDDtp$wjlZdf/LyHTGJ0EfUK3R5Uq5lxhM89I4QMN/6C6TZA0=", "email": "editor@foreverchild.info", "date_joined": "2013-06-12T19:42:49Z"}}, {"pk": 4, "model": "auth.user", "fields": {"username": "chief_editor", "first_name": "Chief", "last_name": "Editor", "is_active": true, "is_superuser": false, "is_staff": true, "last_login": "2013-06-12T19:45:12.777Z", "groups": [1], "user_permissions": [], "password": "pbkdf2_sha256$10000$lWh1xQEmvOtF$EC5zOlAeUhlFuXbV72uSXjGmaeQW5ep5Lzo7p+rD4qE=", "email": "chief-editor@foreverchild.info", "date_joined": "2013-06-12T19:43:36Z"}}]

File example/requirements.txt

 pytz==2013b
 six==1.4.1
 South==0.8.2
-django-werewolf==0.2
+#django-werewolf==0.2
+-e git+https://github.com/barseghyanartur/django-werewolf@stable#egg=django-werewolf