Updated documentation

docs/_templates/indexcontent.html

@@ -10,8 +10,8 @@ <h1>Django-machina</h1>
   <a href="{{ pathto("getting_started") }}" class="btn btn-primary" title="Getting started"><span class="fa fa-bolt">&nbsp;Getting started</span></a>
 </div>
 <div class="figure align-center" id="id2">
-  <p><em>Django-machina</em> is a forum engine for Django providing a way to build community-driven websites. It offers a full-featured yet very extensible forum solution that is designed to be used inside existing Django applications.</p>
-  <p><em>Django-machina</em> is customizable and extensible: each single functionality of the application can be customized or overriden to accommodate with your needs and your own business logic. The central aim of <em>django-machina</em> is to provide a solid core of a forum project - without much of extra functionality included - that can be extended or customized to suit your project needs.</p>
+  <p>Django-machina is a forum engine for Django providing a way to build community-driven websites. It offers a full-featured yet very extensible forum solution that is designed to be used inside existing Django applications.</p>
+  <p>Django-machina is customizable and extensible: each single functionality of the application can be customized or overriden to accommodate with your needs and your own business logic. The central aim of django-machina is to provide a solid core of a forum project - without much of extra functionality included - that can be extended or customized to suit your project needs.</p>
 </div>
 <div class="figure align-center" id="id3">
   <h2>Features</h2>

docs/customization/index.rst

@@ -4,27 +4,33 @@ Customization
 
 
 
-*Django-machina* was built with customization in mind. The module provides useful tools to make your forum compatible with your own business logic.
+Django-machina was built with customization in mind. The module provides useful tools to make your
+forum compatible with your own business logic.
 
 Settings
 --------
 
-As most Django applications do, *django-machina* allows you to customize your forum application with a set of settings (please refer to :doc:`../settings`). *Django-machina*'s settings cover many aspects of your forum: markup language, pagination, images, default permissions, etc.
+As most Django applications do, django-machina allows you to customize your forum application with a
+set of settings (please refer to :doc:`../settings`). Django-machina's settings cover many aspects
+of your forum: markup language, pagination, images, default permissions, etc.
 
 Templates and static files
 --------------------------
 
-If you wish to personalize the look and feel of your forum you can take advantage of the Django's template loading system. Thus you can easily override forum layouts and styles if Django is configured to look in your project first for templates before using the *django-machina*'s templates.
+If you wish to personalize the look and feel of your forum you can take advantage of the Django's
+template loading system. Thus you can easily override forum layouts and styles if Django is
+configured to look in your project first for templates before using the django-machina's templates.
 
-For example, you can easily override *django-machina*'s templates by configuring your template directories as follows in your ``TEMPLATES`` setting::
+For example, you can easily override django-machina's templates by configuring your template
+directories as follows in your ``TEMPLATES`` setting::
 
   import os
 
   TEMPLATES = [
     {
       'BACKEND': 'django.template.backends.django.DjangoTemplates',
       'DIRS': [
-        os.path.join(PROJECT_PATH, 'src/vanilla_project/templates'),
+        os.path.join(PROJECT_PATH, 'myproject/templates'),
         MACHINA_MAIN_TEMPLATE_DIR,
       ],
       'OPTIONS': {
@@ -38,9 +44,12 @@ For example, you can easily override *django-machina*'s templates by configuring
 Advanced customization mechanisms
 ---------------------------------
 
-*Django-machina* relies on a dynamic class loading system that allows to override or extend its Python classes: class-based views, forms, models, etc. This gives you the power to adapt your forum to your own business logic.
+Django-machina relies on a dynamic class loading system that allows to override or extend its Python
+classes: class-based views, forms, models, etc. This gives you the power to adapt your forum to your
+own business logic.
 
-In order to benefit from this dynamic class loading system, you will need to override a *django-machina* application. Please head over to the following topics in order to achieve this:
+In order to benefit from this dynamic class loading system, you will need to override a
+django-machina application. Please head over to the following topics in order to achieve this:
 
 .. toctree::
     :maxdepth: 1
@@ -51,7 +60,8 @@ In order to benefit from this dynamic class loading system, you will need to ove
 Recipes
 -------
 
-Here is a list of simple guides demonstrating how to solve common customization problems when using *django-machina*:
+Here is a list of simple guides demonstrating how to solve common customization problems when using
+django-machina:
 
 .. toctree::
     :maxdepth: 1

docs/customization/overriding_applications.rst

@@ -2,8 +2,8 @@
 Overriding an application
 #########################
 
-*Django-machina* relies on a dynamic class-loading system that allows you to override or extend many
-aspects of its applications. The *django-machina* applications are listed below:
+Django-machina relies on a dynamic class-loading system that allows you to override or extend many
+aspects of its applications. The django-machina applications are listed below:
 
 +-------------------------------+----------------------------------------------------------------------------------------------------+
 | Application name              | Definition                                                                                         |
@@ -28,7 +28,7 @@ aspects of its applications. The *django-machina* applications are listed below:
 .. note::
 
     Overriding these applications is not a trivial task. Most of the time you will need to dig into
-    the source code of *django-machina* in order to discover how things were implemented. This will
+    the source code of django-machina in order to discover how things were implemented. This will
     allow you to find exactly which method should be rewritten in order to achieve the task at hand.
 
 Duplicate the application
@@ -58,7 +58,7 @@ for your overridden applications, as shown below:
 Import the application models if needed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-All *django-machina*'s applications do not necessarily contain models. So this step may be skipped
+All django-machina's applications do not necessarily contain models. So this step may be skipped
 depending on the application you want to override. In the other case, it is necessary to reference
 the models of the overridden application by creating a ``models.py`` file in your package::
 
@@ -71,17 +71,19 @@ the models of the overridden application by creating a ``models.py`` file in you
 
   from machina.apps.forum_conversation.models import *  # noqa
 
-Your overridden application may need to add new models or modify *django-machina*'s own models. As
+Your overridden application may need to add new models or modify django-machina's own models. As
 stated in this snippet, custom models must be declared **before** the import of the
-*django-machina*'s models. This means that you can override a *django-machina* model in order to
-change the way it behaves if you want. Please refer to :doc:`recipes/overriding_models` to get
-detailed instructions on how to override *django-machina*'s models.
+django-machina's models. This means that you can override a django-machina model in order to change
+the way it behaves if you want. Please refer to :doc:`recipes/overriding_models` to get detailed
+instructions on how to override django-machina's models.
 
-Only importing *django-machina*'s models is not enough. You have to ensure the models migrations can
+Only importing django-machina's models is not enough. You have to ensure the models migrations can
 be used by your Django project. You have two possibilities to do so:
 
-  * you can copy the content of the ``migrations`` folder from the application you want to override to your own local application
-  * you can configure the ``MIGRATION_MODULES`` setting to reference the original migrations of the application you want to override
+  * you can copy the content of the ``migrations`` folder from the application you want to override
+    to your own local application
+  * you can configure the ``MIGRATION_MODULES`` setting to reference the original migrations of the
+    application you want to override
 
 ::
 
@@ -91,7 +93,8 @@ be used by your Django project. You have two possibilities to do so:
 
 .. note::
 
-    The second possibility should only be used if you are sure you will not define new models or overridden models into your local application
+    The second possibility should only be used if you are sure you will not define new models or
+    overridden models into your local application
 
 Import the application admin classes if needed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -108,11 +111,11 @@ order to reference the admin classes of the overridden application::
 Define the application AppConfig
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Most of *django-machina*'s applications define sublclasses of Django's ``AppConfig`` which can
-perform initialization operations. *Django-machina* ``AppConfig`` instances are defined inside
-sub-modules called ``registry_config``. You need to define an ``AppConfig`` subclass for your
-custom application by subclassing the overridden application ``AppConfig``. So your application's
-``__init__.py`` should report the custom application ``AppConfig``::
+Most of django-machina's applications define sublclasses of Django's ``AppConfig`` which can perform
+initialization operations. Django-machina ``AppConfig`` instances are defined inside sub-modules
+called ``registry_config``. You need to define an ``AppConfig`` subclass for your custom application
+by subclassing the overridden application ``AppConfig``. So your application's ``__init__.py``
+should report the custom application ``AppConfig``::
 
     default_app_config = 'apps.forum_conversation.registry_config.ConversationRegistryConfig'
 
@@ -127,7 +130,7 @@ And in ``registry_config.py`` in you application you have something like::
 Add the local application to your INSTALLED_APPS
 ------------------------------------------------
 
-Finally you have to tell Django to use your overridden application instead of the *django-machina*'s
+Finally you have to tell Django to use your overridden application instead of the django-machina's
 original application. You can do this by adding your application as a second argument to the
 ``get_apps`` function in your Django settings::
 

docs/customization/recipes/custom_avatar_backend.rst

@@ -2,22 +2,29 @@
 Using a custom avatar backend
 #############################
 
-*Django-machina* has a built-in avatar system to get you started, but if your site uses a different avatar provider, you can modify *django-machina* to use that.
+Django-machina has a built-in avatar system to get you started, but if your site uses a different
+avatar provider, you can modify django-machina to use that.
 
-The first thing we must do is tell *django-machina* to ignore the built-in avatar system::
+The first thing we must do is tell django-machina to ignore the built-in avatar system::
 
   MACHINA_PROFILE_AVATARS_ENABLED = False
 
-This will hide the avatar upload field from the user's account page so they don't upload the avatar to the wrong backend.
+This will hide the avatar upload field from the user's account page so they don't upload the avatar
+to the wrong backend.
 
-Now we have to modify the partial template ``partials/avatar.html`` to use our avatar provider. The template is passed the following two parameters:
+Now we have to modify the partial template ``partials/avatar.html`` to use our avatar provider. The
+template is passed the following two parameters:
 
-- ``profile`` - A ``ForumProfile`` instance for the user (use ``profile.user`` to get the Django ``User``)
-- ``placeholder`` - A boolean telling the template whether or not to show a placeholder for users without an avatar.
+- ``profile`` - A ``ForumProfile`` instance for the user (use ``profile.user`` to get the Django
+  ``User``)
+- ``placeholder`` - A boolean telling the template whether or not to show a placeholder for users
+  without an avatar.
 
 Example: using django-avatar
 ----------------------------
-Here is an example template for `django-avatar <https://github.com/grantmcconnaughey/django-avatar>`_::
+
+Here is an example template for
+`django-avatar <https://github.com/grantmcconnaughey/django-avatar>`_::
 
     {% load avatar_tags %}
     {% if profile.user|has_avatar %}

docs/customization/recipes/overriding_models.rst

@@ -2,16 +2,23 @@
 Overriding application models
 #############################
 
-*Django-machina* allows you to override its models. This can be useful if you want to add new methods or new fields to existing *django-machina* models.
+Django-machina allows you to override its models. This can be useful if you want to add new methods
+or new fields to existing django-machina models.
 
-To illustrate this functionality, we will add an ``icon`` field to the ``Topic`` model (which is part of the ``forum_conversation`` app) in order to allow users select an icon for the topics they create.
+To illustrate this functionality, we will add an ``icon`` field to the ``Topic`` model (which is
+part of the ``forum_conversation`` app) in order to allow users select an icon for the topics they
+create.
 
 Prerequisite
 ------------
 
-Please ensure that you have correctly followed the instructions described in :doc:`../overriding_applications` before trying to override *django-machina* models. If so, you should have created a Python package with the same application label as the app you want to override. This new application should be defined in your ``INSTALLED_APPS`` setting.
+Please ensure that you have correctly followed the instructions described in
+:doc:`../overriding_applications` before trying to override django-machina models. If so, you should
+have created a Python package with the same application label as the app you want to override. This
+new application should be defined in your ``INSTALLED_APPS`` setting.
 
-Most importantly, you should've created a ``models.py`` file inside your package in order to reference the models of the overriden application::
+Most importantly, you should've created a ``models.py`` file inside your package in order to
+reference the models of the overriden application::
 
   # -*- coding: utf-8 -*-
 
@@ -22,14 +29,18 @@ Most importantly, you should've created a ``models.py`` file inside your package
 
   from machina.apps.forum_conversation.models import *  # noqa
 
-Finally you should have copied the content of the ``migration`` folder from the application you want to override into your own local application.
+Finally you should have copied the content of the ``migration`` folder from the application you want
+to override into your own local application.
 
 Defining a new custom model
 ---------------------------
 
-In order to define a new version of an existing *django-machina* model you have to define a new class that subclasses the abstract model class of the model you want to override. The new model you define must have the exact same name as the model you are trying to override.
+In order to define a new version of an existing django-machina model you have to define a new class
+that subclasses the abstract model class of the model you want to override. The new model you define
+must have the exact same name as the model you are trying to override.
 
-For example, in order to define a custom version of the ``Topic`` model it is necessary to subclass the ``machina.apps.forum_conversation.abstract_models.AbstractTopic`` abstract model::
+For example, in order to define a custom version of the ``Topic`` model it is necessary to subclass
+the ``machina.apps.forum_conversation.abstract_models.AbstractTopic`` abstract model::
 
   # -*- coding: utf-8 -*-
 
@@ -48,12 +59,17 @@ For example, in order to define a custom version of the ``Topic`` model it is ne
 
 .. note::
 
-    You need to ensure that the import of *django-machina*'s models is always done at the bottom of your ``models.py`` file. This is very important in the event that you define overridden models because it will ensure that your overriden models will be loaded by Django instead of the original versions provided by *django-machina*.
+    You need to ensure that the import of django-machina's models is always done at the bottom of
+    your ``models.py`` file. This is very important in the event that you define overridden models
+    because it will ensure that your overriden models will be loaded by Django instead of the
+    original versions provided by django-machina.
 
 Creating migrations
 -------------------
 
-As stated previously, you should've copied the content of the ``migration`` folder from the application you want to override into your own local application. Then you just have to create a new migration related to the changes you made to the overriden models:
+As stated previously, you should've copied the content of the ``migration`` folder from the
+application you want to override into your own local application. Then you just have to create a new
+migration related to the changes you made to the overriden models:
 
 .. code-block:: bash