Merge pull request #158 from infoportugal/docs

Document caveats and management commands

docs/caveats.rst

@@ -0,0 +1,33 @@
+.. _caveats:
+
+Caveats
+=======
+
+Wagtail's ``Page`` patch
+------------------------
+
+``wagtail-modeltranslation`` patches Wagtail's ``Page`` model with translation fields
+``title_xx``, ``slug_xx``, ``seo_title_xx``, ``search_description_xx`` and ``url_path_xx``
+where "xx" represents the language code for each translated language. This is done without
+migrations through :ref:`management_commands-sync_page_translation_fields`. Since
+``Page`` model belongs to Wagtail it's within the realm of possibility that one day Wagtail
+may add a conflicting field to ``Page`` thus interfering with ``wagtail-modeltranslation``.
+
+See also :ref:`management_commands-makemigrations_translation` to better understand how
+migrations are managed with ``wagtail-modeltranslation``.
+
+Wagtail's slugurl
+-----------------
+
+Wagtail's ``slugurl`` tag does not work across languages. To work around this
+``wagtail-modeltranslation`` provides a drop-in replacement tag named
+:ref:`template tags-slugurl_trans` which by default takes the slug parameter in the
+default language.
+
+Replace any usages of Wagtail's ``{% slugurl 'default_lang_slug' %}`` for
+
+.. code-block:: django
+
+    {% load wagtail_modeltranslation %}
+    ...
+    {% slugurl_trans 'default_lang_slug' %}

docs/index.rst

@@ -50,6 +50,8 @@ Contents
    Registering Models
    advanced settings
    template tags
+   management commands
+   caveats
    recommended reading
    releases/index
    AUTHORS

docs/management commands.rst

@@ -0,0 +1,111 @@
+.. _management_commands:
+
+Management Commands
+===================
+
+.. _management_commands-wagtail_modeltranslation:
+
+wagtail_modeltranslation
+------------------------
+
+wagtail_modeltranslation module adds the following management commands.
+
+.. _management_commands-update_translation_fields:
+
+The ``update_translation_fields`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This command is a proxy to ``django-modeltranslation``'s own ``update_translation_fields``, for more details read the 
+corresponding documentation on `django-modeltranslation docs
+<http://django-modeltranslation.readthedocs.io/en/latest/commands.html#the-update-translation-fields-command>`_.
+
+In case modeltranslation was installed in an existing project and you
+have specified to translate fields of models which are already synced to the
+database, you have to update your database schema.
+
+Unfortunately the newly added translation fields on the model will be empty
+then, and your templates will show the translated value of the fields which 
+will be empty in this case. To correctly initialize the default translation 
+field you can use the ``update_translation_fields`` command:
+
+.. code-block:: console
+
+    $ python manage.py update_translation_fields
+
+.. _management_commands-sync_page_translation_fields:
+
+The ``sync_page_translation_fields`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.8
+
+This command compares the database and translated Page model definition (finding new translation
+fields) and provides SQL statements to alter ``wagtailcore_page`` table. You should run this command 
+after installation and after adding a new language to your ``settings.LANGUAGES``.
+
+.. code-block:: console
+
+    $ python manage.py sync_page_translation_fields
+
+.. _management_commands-makemigrations_translation:
+
+The ``makemigrations_translation`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.8
+
+``wagtail-modeltranslation`` patches Wagtail's ``Page`` model and as consequence Django's original 
+``makemigrations`` commmand will create migrations for ``Page`` which may create conflicts with 
+other migrations. To circumvent this issue ``makemigrations_translation`` hides any ``Page`` model changes 
+and creates all other migrations as usual. Use this command as an alterntive to Django's own 
+``makemigrations`` or consider using :ref:`management_commands-makemigrations`.
+
+.. code-block:: console
+
+    $ python manage.py makemigrations_translation
+
+.. _management_commands-set_translation_url_paths:
+
+The ``set_translation_url_paths`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Updates url_path translation fields for all pages.
+
+.. code-block:: console
+
+    $ python manage.py set_translation_url_paths
+    
+
+.. _management_commands-wagtail_modeltranslation.makemigrations:
+
+wagtail_modeltranslation.makemigrations
+---------------------------------------
+
+To use ``wagtail_modeltranslation.makemigrations`` module commands add ``'wagtail_modeltranslation.makemigrations,'`` 
+to ``INSTALLED_APPS``. This module adds the following management commands.
+
+.. _management_commands-makemigrations:
+
+The ``makemigrations`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This command is a proxy for :ref:`management_commands-makemigrations_translation`. It has the added benefit of 
+overriding Django's own ``makemigrations`` allowing you to run ``makemigrations`` safely without creating 
+spurious ``Page`` migrations.
+
+.. code-block:: console
+
+    $ python manage.py makemigrations
+
+.. _management_commands-makemigrations_original:
+
+The ``makemigrations_original`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since Django's ``makemigrations`` is overriden by ``wagtail-modeltranslation``'s version use 
+``makemigrations_original`` to run the Django's original ``makemigrations`` command. Please note 
+this will likely create invalid ``Page`` migrations, do this only if you know what you're doing.
+
+.. code-block:: console
+
+    $ python manage.py makemigrations_original

docs/template tags.rst

@@ -14,10 +14,12 @@ Use this template tag to get the url of the current page in another language. Th
     {% load wagtail_modeltranslation %}
     {% change_lang 'pt' %}
 
-slugurl_trans
-===========
+.. _template tags-slugurl_trans:
 
-Use this template tag as a replacement for `slugurl`.
+slugurl_trans
+=============
+
+Use this template tag as a replacement for ``slugurl``.
 
 .. code-block:: django