Merge pull request #286 from nephila/feature/improve_docs

Improve documentation

CONTRIBUTING.rst

@@ -3,15 +3,16 @@ Contributing
 ============
 
 Contributions are welcome, and they are greatly appreciated! Every
-little bit helps, and credit will always be given. 
+little bit helps, and credit will always be given.
 
 You can contribute in many ways:
 
+**********************
 Types of Contributions
-----------------------
+**********************
 
 Report Bugs
-~~~~~~~~~~~
+===========
 
 Report bugs at https://github.com/nephila/djangocms-blog/issues.
 
@@ -22,26 +23,26 @@ If you are reporting a bug, please include:
 * Detailed steps to reproduce the bug.
 
 Fix Bugs
-~~~~~~~~
+========
 
 Look through the GitHub issues for bugs. Anything tagged with "bug"
 is open to whoever wants to implement it.
 
 Implement Features
-~~~~~~~~~~~~~~~~~~
+==================
 
 Look through the GitHub issues for features. Anything tagged with "feature"
 is open to whoever wants to implement it.
 
 Write Documentation
-~~~~~~~~~~~~~~~~~~~
+===================
 
-djangocms-blog could always use more documentation, whether as part of the 
+djangocms-blog could always use more documentation, whether as part of the
 official djangocms-blog docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
 Submit Feedback
-~~~~~~~~~~~~~~~
+===============
 
 The best way to send feedback is to file an issue at https://github.com/nephila/djangocms-blog/issues.
 
@@ -52,8 +53,9 @@ If you are proposing a feature:
 * Remember that this is a volunteer-driven project, and that contributions
   are welcome :)
 
+************
 Get Started!
-------------
+************
 
 Ready to contribute? Here's how to set up `djangocms-blog` for local development.
 
@@ -77,11 +79,9 @@ Now you can make your changes locally.
 5. When you're done making changes, check that your changes pass flake8 and the
 tests, including testing other Python versions with tox::
 
-    $ flake8 djangocms_blog tests
-	$ python setup.py test
     $ tox
 
-To get flake8 and tox, just pip install them into your virtualenv. 
+To get tox, just pip install them into your virtualenv.
 
 6. Commit your changes and push your branch to GitHub::
 
@@ -91,8 +91,9 @@ To get flake8 and tox, just pip install them into your virtualenv.
 
 7. Submit a pull request through the GitHub website.
 
+***********************
 Pull Request Guidelines
------------------------
+***********************
 
 Before you submit a pull request, check that it meets these guidelines:
 
@@ -100,13 +101,14 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check 
+3. The pull request should work for Python 2.7, 3.4, and 3.5. Check
    https://travis-ci.org/nephila/djangocms-blog/pull_requests
    and make sure that the tests pass for all supported Python versions.
 
+****
 Tips
-----
+****
 
 To run a subset of tests::
 
-	$ python -m unittest tests.test_djangocms_blog
+	$ python cms_helper.py test tests.test_views

HISTORY.rst

@@ -1,35 +1,42 @@
 .. :changelog:
 
+=======
 History
--------
+=======
 
+******************
 0.8.5 (2016-06-26)
-++++++++++++++++++
+******************
 
 * Fixed issues with ThumbnailOption migration under mysql.
 
+******************
 0.8.4 (2016-06-22)
-++++++++++++++++++
+******************
 
 * Fixed issues with cmsplugin-filer 1.1.
 
+******************
 0.8.3 (2016-06-21)
-++++++++++++++++++
+******************
 
 * Stricter filer dependency versioning.
 
+******************
 0.8.2 (2016-06-12)
-++++++++++++++++++
+******************
 
 * Aldryn-only release. No code changes
 
+******************
 0.8.1 (2016-06-11)
-++++++++++++++++++
+******************
 
 * Aldryn-only release. No code changes
 
+******************
 0.8.0 (2016-06-05)
-++++++++++++++++++
+******************
 
 * Added django-knocker integration
 * Changed the default value of date_published to null
@@ -43,8 +50,9 @@ History
 * Added API to set default sites if user has permission only for a subset of sites
 * Added Aldryn integration
 
+******************
 0.7.0 (2016-03-19)
-++++++++++++++++++
+******************
 
 * Make categories non required
 * Fix tests with parler>=1.6
@@ -59,29 +67,33 @@ History
 * Mitigate issue when apphook config can't be retrieved
 * Mitigate issue when wizard double registration is triggered
 
+******************
 0.6.3 (2015-12-22)
-++++++++++++++++++
+******************
 
 * Add BLOG_ADMIN_POST_FIELDSET_FILTER to filter admin fieldsets
 * Ensure correct creation of full URL for canonical urls
 * Move constants to settings
 * Fix error when no config is found
 
+******************
 0.6.2 (2015-11-16)
-++++++++++++++++++
+******************
 
 * Add app_config field to BlogLatestEntriesPlugin
 * Fix __str__ plugins method
 * Fix bug when selecting plugins template
 
+******************
 0.6.1 (2015-10-31)
-++++++++++++++++++
+******************
 
 * Improve toolbar: add all languages for each post
 * Improve toolbar: add per-apphook configurable changefreq, priority
 
+******************
 0.6.0 (2015-10-30)
-++++++++++++++++++
+******************
 
 * Add support for django CMS 3.2 Wizard
 * Add support for Apphook Config
@@ -91,8 +103,9 @@ History
 * LatestPostsPlugin tags field has been changed to a plain TaggableManager field.
   A migration is in place to move the data, but backup your data first.
 
+******************
 0.5.0 (2015-08-09)
-++++++++++++++++++
+******************
 
 * Add support for Django 1.8
 * Drop dependency on Django select2
@@ -101,8 +114,9 @@ History
 * Add categories menu
 * Add option to disable the abstract
 
+******************
 0.4.0 (2015-03-22)
-++++++++++++++++++
+******************
 
 * Fix Django 1.7 issues
 * Fix dependencies on python 3 when using wheel packages
@@ -110,14 +124,16 @@ History
 * Fix various templates issues
 * UX fixes in the admin
 
+******************
 0.3.1 (2015-01-07)
-++++++++++++++++++
+******************
 
 * Fix page_name in template
 * Set cascade to set null for post image and thumbnail options
 
+******************
 0.3.0 (2015-01-04)
-++++++++++++++++++
+******************
 
 * Multisite support
 * Configurable default author support
@@ -133,9 +149,9 @@ History
 * Django 1.7 support
 * Python 3.3 and 3.4 support
 
-
+******************
 0.2.0 (2014-09-24)
-++++++++++++++++++
+******************
 
 * **INCOMPATIBLE CHANGE**: view names changed!
 * Based on django parler 1.0
@@ -147,8 +163,8 @@ History
 * Simpler TextField-based content editing for simpler blogs
 * Add support for custom user models
 
-
+******************
 0.1.0 (2014-03-06)
-++++++++++++++++++
+******************
 
 * First experimental release

README.rst

@@ -56,14 +56,15 @@ Supported django CMS versions:
              Some plugins have a broken tag management prior to 0.6, in case
              you have issues with tags, upgrade to latest version to have it fixed.
 
+*****************************************
 Upgrading cmsplugin-filer from 1.0 to 1.1
------------------------------------------
+*****************************************
 
 Due to changes in cmsplugin-filer/filer which moved ``ThumbnailOption`` model from the
 former to the latter, ``djangocms-blog`` must be migrated as well.
 
 Migrating cmsplugin-filer to 1.1 and djangocms-blog up to 0.8.4
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+===============================================================
 
 If you have djangocms-blog up to 0.8.4 (included) installed or you are upgrading from a previous
 djangocms-blog version together with cmsplugin-filer upgrade, you can just apply the migrations::
@@ -72,7 +73,7 @@ djangocms-blog version together with cmsplugin-filer upgrade, you can just apply
     python manage.py migrate
 
 Migrating cmsplugin-filer to 1.1 and djangocms-blog 0.8.5+
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+==========================================================
 
 If you already a djangocms-blog 0.8.5+ or above, you have to de-apply some blog migrations when
 doing the upgrade::
@@ -86,31 +87,35 @@ doing the upgrade::
           to migrate ``ThumbnailOption`` from cmsplugin-filer to filer
 
 
+********
 Features
---------
+********
 
 * Placeholder content editing
 * Frontend editing using django CMS 3.x frontend editor
 * Multilingual support using django-parler
-* Support for Twitter cards, Open Graph and Google+ snippets meta tags
+* Twitter cards, Open Graph and Google+ snippets meta tags
-* Optional support for simpler TextField-based content editing
+* Optional simpler TextField-based content editing
-* Multisite support (posts can be visible in one or more Django sites on the
+* Multisite (posts can be visible in one or more Django sites on the same project)
-  same project)
 * Per-Apphook configuration
 * Configurable permalinks
-* Configurable django CMS menu support
+* Configurable django CMS menu
 * Per-Apphook templates set
 * Auto Apphook setup
-* Django sitemap framework support
+* Django sitemap framework
-* Support for django CMS 3.2+ Wizard
+* django CMS 3.2+ Wizard
-* Haystack index support
+* Haystack index
+* Desktop notifications
+* Liveblog
 
+*************
 Documentation
--------------
+*************
 
 Check documentation at https://djangocms-blog.readthedocs.io/en/latest/
 
+*****************************
 Known djangocms-blog websites
-+++++++++++++++++++++++++++++
+*****************************
 
 See DjangoPackages for an updated list https://www.djangopackages.com/packages/p/djangocms-blog/

djangocms_blog/templates/djangocms_blog/post_detail.html

@@ -21,13 +21,13 @@
     </div>
     {% endif %}
     {% endspaceless %}
-    {% if view.liveblog_enabled %}
-        {% include "liveblog/includes/post_detail.html" %}
-    {% endif %}
     {% if post.app_config.use_placeholder %}
         <div class="blog-content">{% render_placeholder post.content %}</div>
     {% else %}
         <div class="blog-content">{% render_model post "post_text" "post_text" %}</div>
     {% endif %}
+    {% if view.liveblog_enabled %}
+        {% include "liveblog/includes/post_detail.html" %}
+    {% endif %}
 </article>
 {% endblock content_blog %}

docs/channels.rst

@@ -0,0 +1,143 @@
+.. _channels_features:
+
+#################
+Channels Features
+#################
+
+djangocms-blog implements some channels related features:
+
+* desktop notifications
+* liveblog
+
+For how to setup channels in your project, please refer to `channels documentation`_.
+
+.. _knocker:
+
+*************
+Notifications
+*************
+
+``djangocms-blog`` is integrated with `django-knocker`_
+to provide real time desktop notifications.
+
+See `django-knocker documentation`_ for how to configure
+knocker.
+
+
+.. _liveblog:
+
+********
+Liveblog
+********
+
+Liveblog feature allows to display any content on a single post in realtime.
+
+This is implemented by creating a group for each liveblogging enabled post and assigning
+the clients to each group whenever they visit a liveblog post.
+
+Each liveblogged text is a specialized plugin (see `extend_liveblog`_ for information on how to
+customize the liveblog plugin).
+
+
+Enabling liveblog
+=================
+
+To enabled liveblog features:
+
+* Setup django channels according to `channels documentation`_
+
+* Add ``djangocms_blog.liveblog`` application to ``INSTALLED_APPS``::
+
+      INSTALLED_APPS = [
+          ...
+          'djangocms_blog.liveblog',
+          ...
+      ]
+
+* If you overwrite the post detail template, setup the following javascript code in the custom
+  template::
+
+      {% add_data "js-script" "liveblog/js/reconnecting-websocket.min.js" %}
+      {% add_data "js-script" "liveblog/js/liveblog.js" %}
+      <script>
+          var liveblog_apphook = '{{ post.app_config.namespace }}';
+          var liveblog_language = '{{ post.get_current_language }}';
+          var liveblog_post = '{{ post.slug }}';
+      </script>
+
+* It's advised to configure ``CMS_PLACEHOLDER_CONF`` to only allow ``Liveblog`` plugins in
+  ``Liveblog`` placeholder, and remove them from other placeholders::
+
+      CMS_PLACEHOLDER_CONF = {
+        None: {
+            'excluded_plugins': ['LiveblogPlugin'],
+        }
+        ...
+        'liveblog': {
+            'plugins': ['LiveblogPlugin'],
+        }
+        ...
+      }
+
+
+Using liveblog
+==============
+
+To use liveblog:
+
+* Tick the ``enable liveblog`` flag in the ``Info`` fieldset;
+* Open the blog post detail page;
+* Optionally add static content to the ``post content`` placeholder; the default template will
+  show static content on top of liveblog content; you can override the template for different
+  rendering;
+* Add plugins to the ``Liveblog`` placeholder;
+* Tick the ``publish`` flag on each ``Liveblog`` plugin to send it to clients in realtime.
+
+
+.. _extend_liveblog:
+
+Extending liveblog plugin
+=========================
+
+Liveblog support ships with a default liveblog plugin that provides a title, a body and
+a filer image.
+
+To customize the appearance of the plugin, just override the ``liveblog/plugins/liveblog.html``
+template. Both the real time and non realtime version of the plugin will be rendered accordingly.
+
+If you need something different, you can create your own plugin by creating your own plugin
+inheriting from ``LiveblogInterface`` and calling the method ``self._post_save()`` in the
+save method, after the model has been saved.
+
+In ``models.py``:
+
+.. code-block:: django
+
+    class MyLiveblog(LiveblogInterface, CMSPlugin):
+    """
+    Basic liveblog plugin model
+    """
+    text = models.TextField(_('text'))
+
+    def save(self, *args, **kwargs):
+        super(MyLiveblog, self).save(*args, **kwargs)
+        self._post_save()
+
+
+The plugin class does not require any special inheritance; in ``cms_plugins.py``:
+
+.. code-block:: django
+
+    class MyLiveblogPlugin(CMSPluginBase):
+        name = _('Liveblog item')
+        model = MyLiveblog
+    plugin_pool.register_plugin(MyLiveblogPlugin)
+
+While not required, for consistency between between realtime and non realtime rendering, use the
+``publish`` field inherited from ``LiveblogInterface`` to hide the plugin content when the plugin
+is not published.
+
+
+.. _channels documentation: http://channels.readthedocs.io/en/latest/index.html
+.. _django-knocker documentation: http://django-knocker.readthedocs.io/en/latest/index.html
+.. _django-knocker: https://github.com/nephila/django-knocker

docs/features.rst

@@ -1,12 +1,14 @@
 .. _features:
 
+========
 Features
---------
+========
 
 .. _blog-home-page:
 
+*******************************
 Attaching blog to the home page
-+++++++++++++++++++++++++++++++
+*******************************
 
 If you want to attach the blog to the home page you have to adapt settings a bit otherwise the
 "Just slug" permalink will swallow any CMS page you create.
@@ -32,13 +34,14 @@ linked ot the home page (see http://yoursite.com/admin/djangocms_blog/blogconfig
 
 .. _multisite:
 
+*********
 Multisite
-+++++++++
+*********
 
 django CMS blog provides full support for multisite setups.
 
 Basic multisite
-^^^^^^^^^^^^^^^
+===============
 
 To enabled basic multisite add ``BLOG_MULTISITE = True`` to the project settings.
 
@@ -47,7 +50,7 @@ it's visible on all sites. All users with permission on the blog can manage all
 posts, whichever the sites are.
 
 Multisite permissions
-^^^^^^^^^^^^^^^^^^^^^
+=====================
 
 Multisite permissions allow to restrict users to only manage the blog posts for the
 sites they are enabled to
@@ -65,8 +68,9 @@ Example::
 
 .. _cms-wizard:
 
+**********************
 django CMS 3.2+ Wizard
-++++++++++++++++++++++
+**********************
 
 django CMS 3.2+ provides a content creation wizard that allows to quickly created supported
 content types, such as blog posts.
@@ -80,8 +84,9 @@ wizard may not show up, but the rest will work as intended.
 
 .. _permalinks:
 
+***********************
 Configurable permalinks
-+++++++++++++++++++++++
+***********************
 
 Blog comes with four different styles of permalinks styles:
 
@@ -106,8 +111,9 @@ And change ``post/`` with the desired prefix.
 
 .. _menu:
 
+****
 Menu
-++++
+****
 
 ``djangocms_blog`` provides support for django CMS menu framework.
 
@@ -121,8 +127,9 @@ category are not added to the menu.
 
 .. _templates:
 
+*********
 Templates
-+++++++++
+*********
 
 To ease the template customisations a ``djangocms_blog/base.html`` template is
 used by all the blog templates; the templates itself extends a ``base.html``
@@ -133,8 +140,9 @@ not defines a ``content`` block, copy in your template directory
 other application templates will use the newly created base template and
 will ignore the bundled one.
 
+*************
 Templates set
-+++++++++++++
+*************
 
 By using **Apphook configuration** you can define a different templates set.
 To use this feature provide a directory name in **Template prefix** field in
@@ -143,8 +151,9 @@ root of your custom templates set.
 
 .. _sitemap:
 
+*******
 Sitemap
-+++++++
+*******
 
 ``djangocms_blog`` provides a sitemap for improved SEO indexing.
 Sitemap returns all the published posts in all the languages each post is available.
@@ -168,14 +177,3 @@ To add the blog Sitemap, add the following code to the project ``urls.py``::
             }
         }),
     )
-
-.. _knocker:
-
-django-knocker
-++++++++++++++
-
-``djangocms-blog`` is integrated with `django-knocker <https://github.com/nephila/django-knocker>`_
-to provide real time desktop notifications.
-
-See `django-knocker documentation <https://django-knocker.readthedocs.io/>`_ for how to configure
-knocker.

docs/index.rst

@@ -3,14 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+==========================================
 Welcome to djangocms-blog's documentation!
 ==========================================
 
 .. include:: ../README.rst
 
 
+********
 Contents
---------
+********
 
 .. toctree::
    :maxdepth: 2
@@ -18,13 +20,15 @@ Contents
    installation
    settings
    features
+   channels
    development
    contributing
    history
 
 
+******************
 Indices and tables
-==================
+******************
 
 * :ref:`genindex`
 * :ref:`search`

docs/installation.rst

@@ -1,7 +1,8 @@
 .. _installation:
 
+############
 Installation
-------------
+############
 
 Install djangocms-blog::
 
@@ -28,8 +29,9 @@ Then migrate::
 
     $ python manage.py migrate
 
+*********************
 Minimal configuration
-+++++++++++++++++++++
+*********************
 
 The following are minimal defaults to get the blog running; they may not be
 suited for your deployment.
@@ -90,8 +92,9 @@ suited for your deployment.
 
 .. _external_applications:
 
+***********************************
 External applications configuration
-+++++++++++++++++++++++++++++++++++
+***********************************
 
 Dependency applications may need configuration to work properly.
 
@@ -106,8 +109,9 @@ Please, refer to each application documentation on details.
 
 .. _auto_setup:
 
+**********
 Auto setup
-++++++++++
+**********
 
 ``djangocms_blog`` can install and configue itself if it does not find any
 attached instance of itself.

docs/settings.rst

@@ -1,7 +1,9 @@
 .. _settings:
 
+###############
 Global Settings
----------------
+###############
+
 * BLOG_IMAGE_THUMBNAIL_SIZE: Size of the main image when shown on the post
   lists; it's a dictionary with ``size``, ``crop`` and ``upscale`` keys;
   (default: ``{'size': '120x120', 'crop': True,'upscale': False}``)
@@ -88,8 +90,9 @@ Global Settings
 * BLOG_FEED_LATEST_ITEMS: Number of items in latest items feed
 * BLOG_FEED_TAGS_ITEMS: Number of items in per tags feed
 
+******************
 Read-only settings
-++++++++++++++++++
+******************
 
 * BLOG_MENU_TYPES: Available structures of the Blog menu; (default list **Posts and Categories**,
   **Categories only**, **Posts only**, **None**)
@@ -97,8 +100,9 @@ Read-only settings
   (default: ``Posts and Categories``)
 
 
+********************
 Per-Apphook settings
-++++++++++++++++++++
+********************
 
 The following settings can be configured for each ``Apphook config``: the settings above will
 be used as defaults.