some cleanups, coding style doc

book.json

@@ -7,5 +7,8 @@
       "url": "https://github.com/rafalp/Misago/"
     }
   },
-  "root": "./docs"
+  "root": "./docs",
+  "variables": {
+    "django_version": "1.10"
+  }
 }

docs/CodingStyle.md

@@ -0,0 +1,140 @@
+Coding Style and Conventions
+============================
+
+When writing Python code for Misago, please familiarize yourself with and follow those documents:
+
+1. [PEP 8](http://www.python.org/dev/peps/pep-0008/)
+2. [Django Coding Style and Conventions](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/)
+
+Those documents should give you solid knowledge of coding style and conventions that are followed by Python and Django programmers when writing code.
+
+In addition to those guidelines, Misago defines set of additional convetions and good practices that will help you write better and easier code.
+
+
+##### Notes
+
+Originally Misago was writen with 79 character line limit in mind, but recently this convention was dropped for sake of Django's 119 characters line limit. 
+
+Misago comes with `.pylintrc` file that contains configuration for pylint tool used to lint Misago's codebase.
+
+
+## Single and double quotes
+
+Write messages intented for humans to see using double quotes and all other strings using single ones. Use single quotes for messages for humans if those already contain double quotes.
+
+```python
+# good
+message = "Your account has been banned!"
+message = 'You cannot use "%(username)s" as username!'
+
+Category.objects.get(role='threads')
+
+# bad
+message = 'Your account has been banned!'
+
+Category.objects.get(role="threads")
+```
+
+
+## Models
+
+
+### Fields Order
+
+When declaring model's database fields, start with taxonomical foreign keys followed by fields that make this model identifiable to humans. Order of remaining fileds is completely up to you.
+
+Thread model is great example of this convention. Thread is part of taxonomy (Forum), so first field defined is foreign key to Forum model. This is followed by two fields that humans will use to recognise this model: `title` that will be displayed in UI and `slug` that will be included in links to this thread. After those Thread model defines additional fields.
+
+When declaring model database fields, make sure they are grouped together based on their purpose. Most common example is storage of user name and slug in addition to foreign key to User model. In such case, make sure both `poster` field as well as `poster_name`, `poster_slug` and `poster_ip` fields are grouped together.
+
+
+### Avoid Unmeaningful Names
+
+Whenever possible avoid naming fields representing relation to `User` model `user`. Preffer more descriptive names like `poster`, `last_editor`, or `giver`.
+
+For same reason avoid using `date` or `ip` as field names. Use more descriptive `posted_on` or `poster_ip` instead.
+
+
+### True/False Fields
+
+For extra clarity prefix fields representing true/false states of model with `is_`. `is_deleted` is better than `deleted`.
+
+
+## Serializers
+
+
+### Defining serializers
+
+Model's default serializer should be named after its model, but with `Serializer` suffix, ergo serializer for `Thread` model should be named `ThreadSerializer`. Default serializer should be only serializer defining serialization methods for `SerializerMethodField`.
+
+In case that model has more than one serializer, all additional serializers should be named in a way describing their usage. For example serializer for `Post` model used to serialize user's posts list could be named `FeedPostsSerializer`. This serializer should only define `Meta` class with `model` and `fields` attributes, inheriting serialization behaviour form default serializer.
+
+
+### Fields Order
+
+Order of fields should correspond directly to order of fields on model that serializer handles.
+
+If serializer defines non-model fields, those should be specified last and separated from model's fields with empty line, ergo:
+
+```python
+fields = (
+    'id',
+    'user',
+    'title',
+
+    'acl', # annotation set on model by view
+    'something_extra', # dynamic atribute coming from "SerializerMethodField"
+)
+```
+
+
+### URLs
+
+Serializers may define two special fields used for serialization of url's, `url` and `api`. The first one should be string containing serialized model's `get_absolute_url` or list urls of interest for UI rendering serialized model, like:
+
+```python
+'url': {
+    'absolute': obj.get_absolute_url(),
+    'first_unread': obj.get_first_unread_url(),
+    'last_post': obj.get_last_post_url(),
+}
+```
+
+Likewise the "api" key should contain the url to item api endpoint (eg. `/api/threads/132/`) or list of avaiable endpoints:
+
+```python
+'api': {
+    'index': reverse('misago:api:threads', kwargs={'pk': obj.pk}),
+    'read': reverse('misago:api:thread-read', kwargs={'pk': obj.pk}),
+    'move': reverse('misago:api:thread-move', kwargs={'pk': obj.pk}),
+}
+```
+
+Those keys should live at the end of the fields list and be separated from other fields with blank line:
+
+```python
+fields = (
+    'id',
+    'user',
+    'title',
+
+    'acl', # annotation set on model by view
+    'something_extra', # dynamic atribute coming from "SerializerMethodField"
+
+    'api',
+    'url',
+)
+```
+
+
+### Nested results
+
+Nested results should be included in view or viewset, as part of creating dict of serialized data for `Response` object:
+
+```python
+data = UserSerializer(user).data
+data['post_set'] = UserPostSerializer(posts, many=True).data
+return Response(data)
+```
+
+The added key should be model's `related_name` in respect of model it annotates (defautly its `modelname_set`).

docs/SUMMARY.md

@@ -3,7 +3,7 @@
 * [Introduction](./README.md)
 * [Setup and Maintenance](./SetupMaintenance.md)
 * [Upgrading from Misago 0.5](./UpgradingFrom05.md)
-* [References](./ref/README.md)
-  * [Settings](./ref/settings/README.md)
-    * [Core settings](./ref/settings/Core.md)
-    * [Database settings](./ref/settings/Database.md)
+* [Coding style](./CodingStyle.md)
+* [Settings](./settings/README.md)
+  * [Core settings](./settings/Core.md)
+  * [Database settings](./settings/Database.md)

docs/SetupMaintenance.md

@@ -41,21 +41,15 @@ Once you've decided on your name, create your site configuration module. In exam
 
 This will create directory "misagoforumorg" in your working directory. Inside you will find following items:
 
-* ``manage.py`` script that you can use to run administrative commands Misago provides as well as access its python shell which is usefull for quick and dirty administration work.
+* `manage.py` script that you can use to run administrative commands Misago provides as well as access its python shell which is usefull for quick and dirty administration work.
+* `cron.txt` that contains example crontab configuration for automating maintenance tasks on your site.
+* `avatargallery` directory that contains example avatar gallery you may load using `manage.py` script to run `loadavatargallery` task that will load it into avatar gallery.
+* `media` directory for user uploaded files.
+* `misagoforumorg` python module with configuration files for your site.
+* `static` directory for static assets like css, js or images.
+* `theme` directory for overriding default assets with your own ones.
 
-* ``cron.txt`` that contains example crontab configuration for automating maintenance tasks on your site.
-
-* ``avatargallery`` directory that contains example avatar gallery you may load using ``manage.py`` script to run ``loadavatargallery`` task that will load it into avatar gallery.
-
-* ``media`` directory for user uploaded files.
-
-* ``misagoforumorg`` python module with configuration files for your site.
-
-* ``static`` directory for static assets like css, js or images.
-
-* ``theme`` directory for overriding default assets with your own ones.
-
-We will get to ``misagoforumorg`` in a minute, but before that lets spend few more moments in our current location.
+We will get to `misagoforumorg` in a minute, but before that lets spend few more moments in our current location.
 
 This directory has special purpose. It serves as "container" for your customizations for Misago. If you want to install extension or plugin that has no `setup.py` of its own or use custom styles or templates on your site, you will put them there, making them easily accessible for your Misago installation.
 
@@ -95,4 +89,4 @@ If you need example, UWSGI project's documentation has tutorial on configuring N
 
 ### Securing MEDIA_ROOT
 
-By default Misago uses the ``FileSystemStorage`` strategy that stores user-uploaded files in your site's ``media`` directory. You need to make sure that you have disabled indexing/listing of this directory contents in your HTTP server's settings, or your user-uploaded files will be easily discoverable from internet. This is especially important because Misago has no special protection system in place for uploaded files.
+By default Misago uses the `FileSystemStorage` strategy that stores user-uploaded files in your site's `media` directory. You need to make sure that you have disabled indexing/listing of this directory contents in your HTTP server's settings, or your user-uploaded files will be easily discoverable from internet. This is especially important because Misago has no special protection system in place for uploaded files.

docs/UpgradingFrom05.md

@@ -59,7 +59,7 @@ To move configuration over to new forum, run `python manage.py movesettings` com
 
 #### Note:
 
-Some settings have been moved from admin to configuration file or removed. Those will not be migrated. Please consult the [reference](./ref/settings/README.md) for available settings that you will need to add yourself.
+Some settings have been moved from admin to configuration file or removed. Those will not be migrated. Please consult the [reference](./settings/README.md) for available settings that you will need to add yourself.
 
 
 ## Moving users

docs/ref/README.md

@@ -1,4 +0,0 @@
-References
-==========
-
-* [Settings](./settings/README.md)

docs/ref/settings/README.md

@@ -1,13 +0,0 @@
-Settings
-========
-
-
-[Core settings](./Core.md)
-[Database settings](./Database.md)
-
-
-# Django Settings Reference
-
-Django defines plenty of configuration options that control behaviour of different features that Misago relies on.
-
-Those are documented and available in [Django documentation](https://docs.djangoproject.com/en/1.6/ref/settings/).

docs/ref/settings/Core.md → docs/settings/Core.md

@@ -1,7 +1,7 @@
 Core Settings
 =============
 
-Those settings are set in `settings.py` file and available via `django.conf.settings` or `misago.conf.settings`
+Those settings are set in `settings.py` file with defaults defined in `misago.conf.defaults` module. 
 
 
 ## MISAGO_403_IMAGE

docs/ref/settings/Database.md → docs/settings/Database.md

@@ -1,7 +1,7 @@
 Database Settings
 =================
 
-Those settings are stored in database and are available via `misago.conf.settings`. To change those settings you need to use admin control panel
+Those settings are stored in database and are available via `misago.conf.settings`. To change those settings you need to use admin control panel.
 
 
 ## account_activation

docs/settings/README.md

@@ -0,0 +1,39 @@
+Settings
+========
+
+Misago splits its settings into two groups:
+
+
+## Core settings
+
+Those settings must be available when Misago starts or control resources usage and shouldn't be changed frequently from admin control panel. Those settings live in settings.py
+
+[Core settings reference](./Core.md)
+
+
+## Database settings
+
+Those settings are stored in database and can be changed on runtime using interface provided by admin control panel.
+
+[Database settings reference](./Database.md)
+
+
+## Accessing settings in template
+
+Both types of settings can accessed as attributes of `misago.conf.settings` object and high level settings can be also accessed from your templates as attributes of `misago_settings` variable, like this:
+
+```
+<h1>{{ misago_settings.forum_name }}</h1> // will produce <h1>Misago Forums</h1>
+```
+
+
+##### Note
+
+Not all high level settings values are available at all times. Some settings ("lazy settings"), are evaluated to True or None immediately upon load. This means that they can be checked to see if they have value or not, but require you to use special `settings.get_lazy_setting(setting)` getter to obtain their real value.
+
+
+## Django Settings Reference
+
+Django defines plenty of configuration options that control behaviour of different features that Misago relies on.
+
+Those are documented and available in [Django documentation](https://docs.djangoproject.com/en/{{ book.django_version }}/ref/settings/).