#658 - proffread some docs, readme and setup manual

docs/conf.py

@@ -49,7 +49,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Misago Documentation'
-copyright = u'2014, Rafał Pitoń'
+copyright = u'2017, Rafał Pitoń'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/developers/settings.rst

@@ -20,18 +20,15 @@ Both types of settings can accessed as attributes of ``misago.conf.settings`` ob
 Defining Custom DB Settings
 ===========================
 
-.. note::
-   Current Misago 0.6 migrations are south-based placeholders that will be replaced with new migrations introduced in Django 1.7 before release. For this reason this instruction focuses exclusively on usage of utility function provided by Misago.
-
 In order to define or change high-level (stored in database) settings you have to add new rows to ``conf_settingsgroup`` and ``conf_settings`` database tables. This can be done by plenty of different ways, but preffered one is by creating new data migration and using functions from ``misago.conf.migrationutils`` module.
 
 
 migrate_settings_group
 ----------------------
 
-.. function:: migrate_settings_group(orm, group_fixture, old_group_key=None)
+.. function:: migrate_settings_group(apps, group_fixture, old_group_key=None)
 
-This function uses south supplied ORM instance to insert/update settings group in database according to provided dict contianing its name, description and contained settings. If new group should replace old one, you can provide its key in ``old_group_key`` argument.
+This function uses Django supplied ``apps`` instance to insert/update settings group in database according to provided dict contianing its name, description and contained settings. If new group should replace old one, you can provide its key in ``old_group_key`` argument.
 
 The ``group_fixture`` dict should define following keys:
 
@@ -56,34 +53,12 @@ Each dict in ``settings`` tuple should define following keys:
 
 
 .. note::
-   If you wish to make your names and messages translateable, you should use ``ugettext_lazy`` function provided by Misago instead of Django one. This function is defined in ``misago.core.migrationutils`` module and differs from Django one by the fact that it preserves untranslated message on its ``message`` attribute.
-
-   For your convience ``migrate_settings_group`` triess to switch translation messages with their "message" attribute when it writes to database and thus making their translation to new languages in future possible.
-
-
-with_conf_models
-----------------
-
-.. function:: with_conf_models(migration, this_migration=None)
-
-South migrations define special ``models`` attribute that holds dict representing structure of database at time of migration execution. This dict will by default contain only your apps models. To add settings models that ``migrate_settings_group`` requires to work, you have to use ``with_conf_models`` function. This function accepts two arguments:
-
-* **migration** - name of migration in ``misago.conf`` app containing models definitions current for the time of your data migration.
-* **this_migration** - dict with model definitions for this migration.
-
-In addition to this, make sure that your migration ``depends_on`` attribute defines dependency on migration from ``misago.conf`` app::
-
-    class Migration(DataMigration):
-
-        # Migration code...
+   If you wish to make your names and messages translateable, you should define fake ``gettext`` function in your code to wrap translated strings with:
 
-        models = with_conf_models('0001_initial', {
-            # This migration models
-        })
+       _ = lambda x: x
 
-        depends_on = (
-            ("conf", "0001_initial"),
-        )
+       # below line will be made translatable by makemessages:
+       _('Some string')
 
 
 delete_settings_cache

docs/developers/template_tags.rst

@@ -5,25 +5,6 @@ Template Tags Reference
 Misago defines plenty of custom tags and filters for use by template authors.
 
 
-misago_avatars
-==============
-
-``avatar`` filter
------------------
-
-Accepts user model instance or integer representing user's PK, returns link to avatar server that can be used as ``src`` attribute value for ``img``.
-
-Takes one optional argument, image size.
-
-
-``blankavatar`` tag
--------------------
-
-Returns link to avatar blank avatar that can be used as ``src`` attribute value for ``img``. Should be used when no user pk is avaialable to render avatar, eg. displaying items belonging to deleted users.
-
-Takes one optional argument, image size.
-
-
 misago_batch
 ============
 
@@ -39,7 +20,7 @@ Takes one argument, integer individual batch length, then turns big list into li
 
 
 ``batchnonefilled`` filter
-----------------
+--------------------------
 
 Works same as ``batch`` filter, but with one difference:
 
@@ -75,12 +56,6 @@ misago_editor
 Renders Misago Markup editor body in template. Requires one argument: variable containing editor instance.
 
 
-``editor_js`` tag
------------------
-
-Renders Misago Markup editor's javascript in template. Requires one argument: variable containing editor instance.
-
-
 misago_forms
 ============
 
@@ -124,17 +99,3 @@ Shorthand for simple if clauses: ``{{ "fade in"|iftrue:thread.is_closed }}`` wil
 -----------------
 
 Opposite filter for ``iftrue``.
-
-
-misago_pagination
-=================
-
-Shortcut for rendering paginators using template. Accepts following arguments:
-
-* **page** - paginator's page object
-* **template** - template to use to render paginator
-* **link_name** - link name to use for pages
-
-Also accepts kwargs which will be passed to template context as they were given to tag.
-
-Paginator template gets ``paginator``, ``page`` and ``link_name`` values to use in rendering.

docs/setup_maintenance.rst

@@ -8,7 +8,7 @@ Misago is Python and Django application which means system requirements as well
 Installing Misago
 =================
 
-Misago installation is three step process. First you compare your server's specification to check if will be able to run Misago. Next you setup Misago and all extra services required for it to function like e-mails, database and automatic maintenance jobs. Finally you get your site running and accessible for your users.
+Misago installation is three step process. First you compare your server's specification to check if will be able to run Misago. Next you setup Misago and all extra services required for it to function like e-mails, database and automatic maintenance tasks. Finally you get your site running and accessible for your users.
 
 
 Requirements
@@ -17,13 +17,13 @@ Requirements
 Before you start make sure your hosting provider grants you:
 
 - SSH access to the server
-- Python 2.7 or 3.5
+- Python 2.7, 3.4, 3.5 or 3.6
 - PostgreSQL >= 9.4
 - At least 128 megabytes of free memory for Misago's processes
-- HTTP server that supports WSGI applications
+- HTTP server that supports WSGI applications (like NGINX with UWSGI or Apache2 with mod_wsgi)
 - Crontab
 
-This isn't an issue on VPS or dedicated servers, but availability of shared servers that meet those requirements differs from country to country.
+This isn't an issue on VPS or dedicated servers, but availability of shared servers that meet those requirements differs wildly depending on your location.
 
 Speaking of shared servers, ability to download, compile and run software from internet may be needed, but different ISP's have different approach to this. Some options come with all dependencies preinstalled, others let you install them yourself and others require you to mail them every time you need something installed. Generally you should avoid offers coming from last group because this turns running Python apps into a hore.
 
@@ -33,17 +33,33 @@ Setup
 
 To install Misago setup and activate virtual environment for your site and then fire following command::
 
-    python setup.py install
+    pip install misago
 
 This will install Misago in your virtual environment and make "misago-start.py" script available for you to use to create pre-configured Misago site.
 
-Now decide on your site's "name". This name will be used for python module that will contain your configuration files. This means it should be only latin lowercase letters and (optionally) digits and underscore sign ("_"). Good idea is to use your domain name as source for project namespace, for example turning "misago-forum.org" into "misagoforumorg".
+Now decide on your site's module name. This name will be used for python module that will contain your configuration files. This means it should be only latin lowercase letters and (optionally) digits or underscore sign ("_"). Good idea is to use your domain name as source for project namespace, for example turning "misago-forum.org" into "misagoforumorg".
 
 Once you've decided on your name, create your site configuration module. In example we assume your site will be named "misagoforumorg"::
 
 	misago-start.py misagoforumorg
 
-This will create directory "misagoforumorg" in your working directory. Inside you will find "manage.py" file 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. In addition to this file you will find "cron.txt" that contains example crontab configuration for automating maintenance tasks on your site and "requirements.txt" that you can use as reference of versions of libraries Misago relies on to run. In addition to those, you will find one more "misagoforumorg" here, containing python module with configuration files for your site. We will get to it in a minute, but before that lets spend few more moments in our current location.
+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.
+
+* ``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.
 
 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.
 
@@ -76,8 +92,10 @@ Deployment is a process in which you get your site running and reachable by your
 
 Misago is de facto Django with extra features added. This means deployment of Misago should be largery same to deployment of other Django-based solutions. Django documentation `already covers <https://docs.djangoproject.com/en/1.6/howto/deployment/>`_ supported deployment methods, and while on dedicated and VPS options deployment method depends largery on your choice and employed software stack, shared servers may differ greatly by the way how Django should be deployed. If thats the case, make sure you consult your ISP documentation and/or ask its rep for details about supported deployment method.
 
+If you need example, UWSGI project's documentation has tutorial on configuring NGINX with UWSGI to run `django applications <http://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html>`_
+
 
 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 of this directory contents in your HTTP server's settings, or your user-uploaded files will be discoverable by 3rd party.
+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.

misago/conf/migrationutils.py

@@ -4,6 +4,41 @@ from .dbsettings import CACHE_KEY
 from .hydrators import dehydrate_value
 
 
+def migrate_settings_group(apps, group_fixture, old_group_key=None):
+    SettingsGroup = apps.get_model('misago_conf', 'SettingsGroup')
+    Setting = apps.get_model('misago_conf', 'Setting')
+    group_key = group_fixture['key']
+
+    # Fetch settings group
+
+    if old_group_key:
+        group = get_group(SettingsGroup, old_group_key)
+        custom_settings_values = get_custom_settings_values(group)
+    else:
+        group = get_group(SettingsGroup, group_key)
+        if group.pk:
+            custom_settings_values = get_custom_settings_values(group)
+        else:
+            custom_settings_values = {}
+
+    # Update group's attributes
+
+    group.key = group_fixture['key']
+    group.name = group_fixture['name']
+    if group_fixture.get('description'):
+        group.description = group_fixture.get('description')
+    group.save()
+
+    # Delete groups settings and make new ones
+    # Its easier to create news ones and then assign them old values
+
+    group.setting_set.all().delete()
+
+    for order, setting_fixture in enumerate(group_fixture['settings']):
+        old_value = custom_settings_values.pop(setting_fixture['name'], None)
+        migrate_setting(Setting, group, setting_fixture, order, old_value)
+
+
 def get_group(SettingsGroup, group_key):
     try:
         return SettingsGroup.objects.get(key=group_key)
@@ -58,40 +93,5 @@ def migrate_setting(Setting, group, setting_fixture, order, old_value):
     setting.save()
 
 
-def migrate_settings_group(apps, group_fixture, old_group_key=None):
-    SettingsGroup = apps.get_model('misago_conf', 'SettingsGroup')
-    Setting = apps.get_model('misago_conf', 'Setting')
-    group_key = group_fixture['key']
-
-    # Fetch settings group
-
-    if old_group_key:
-        group = get_group(SettingsGroup, old_group_key)
-        custom_settings_values = get_custom_settings_values(group)
-    else:
-        group = get_group(SettingsGroup, group_key)
-        if group.pk:
-            custom_settings_values = get_custom_settings_values(group)
-        else:
-            custom_settings_values = {}
-
-    # Update group's attributes
-
-    group.key = group_fixture['key']
-    group.name = group_fixture['name']
-    if group_fixture.get('description'):
-        group.description = group_fixture.get('description')
-    group.save()
-
-    # Delete groups settings and make new ones
-    # Its easier to create news ones and then assign them old values
-
-    group.setting_set.all().delete()
-
-    for order, setting_fixture in enumerate(group_fixture['settings']):
-        old_value = custom_settings_values.pop(setting_fixture['name'], None)
-        migrate_setting(Setting, group, setting_fixture, order, old_value)
-
-
 def delete_settings_cache():
     default_cache.delete(CACHE_KEY)

setup.py

@@ -9,8 +9,6 @@ from misago import __version__ as version
 SETUP_DIR = os.path.dirname(__file__)
 
 
-README = open(os.path.join(SETUP_DIR, 'README.rst')).read()
-
 with open(os.path.join(SETUP_DIR, 'requirements.txt'), "r") as f:
     REQUIREMENTS = [x.strip() for x in f.readlines()]
 
@@ -29,8 +27,11 @@ setup(
     name='Misago',
     version=version,
     license='GNU General Public License v2 (GPLv2)',
-    description='Misago is complete, featured and modern forum solution.',
-    long_description=README,
+    description=[
+        "Misago is modern, fully featured forum application written in "
+        "Python and ES6, powered by Django and React.js. It works out of "
+        "the box and plays nice with other projects like Django-CMS."
+    ],
     url='http://www.misago-project.org/',
     author=u'Rafał Pitoń',
     author_email='kontakt@rpiton.com',
@@ -53,7 +54,9 @@ setup(
         'Operating System :: OS Independent',
         'Programming Language :: Python',
         'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
         'Topic :: Internet :: WWW/HTTP',
         'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
         "Topic :: Internet :: WWW/HTTP :: WSGI",