Some points about documentation

[bbirand]

Thanks a lot for a great package, dfunkct!

The documentation is great, and I'm trying to get onboard. But even though a lot of things are pretty clear, certain things are still a bit confusing, and I think making them clearer in the documentation would really make this more approachable.

Namely;

• You write rules.predicate and rules.add_rule, but at no point is there an import rules statement. For the decorator, this is kinda understandable, as it's common to import decorators from modules. But for add_rule, it wasn't clear what that variable was. Are these running on the module itself?
• You mention that there are two rule sets, one shared one, and the other for Django. How do you access these? When I do rules.add_rule, which one does it get added to? Is the Django one implicit?
• Where do we add these rules? Doing so in the view function is the most obvious choice. You mention adding a rule.py module in the app, which makes sense. What is the content of this module then? Just import rules, and then add the rules? And then do another import rules in views.py, and start using the decorators?

In general, I imagine many people will use rules from a Django app. A minimal example would really help. Also, a lot of info about settings things up is spread around the file. Installing using pip is a no-brainer. But there should also be a Django configuration section for things like:

• Adding the app to INSTALLED_APPS
• Adding rules to AUTHENTICATION_BACKENDS
• Adding a rules.py file.

Sorry if this is long, but it's by no means a rant. On the contrary, I'm really excited about using this library, and I think it would really benefit from a few tweaks to the documentation!

[bbirand]

Ok, I see now the distinction between the shared ruleset and the Django permission ruleset.. But given that this is called "django-rules" and most people are therefore likely to use it from Django, would it not make sense to mainly talk about the Django version, and save the generic version to an appendix or so?

[dfunckt]

Hi, excuse my late reply. All fair points -- I'm aware docs can be improved, but then again isn't it always the case ;) Being both the author of the library and its documentation, it's easy to lose newcomer's perspective, so your feedback is valuable.

I'll try to restructure the readme a bit and clarify some points you brought up so that things will become clearer. In the meantime, if you still have specific questions, I'd be happy to answer.

[Bluejanis]

Hey I am a newcomber both to django and this library. I tried configuring rules to be able to set object permissions within the django admin interface. From the docs I got it all configured, but I had to read the whole doc, since the django part doesn't explain (or link) the predicates. And I didnt get it working. When a predicate gets called django only fills the first parameter. The object is always None.