Merge pull request #286 from nephila/feature/improve_docs

Improve documentation
This commit is contained in:
Iacopo Spalletti 2016-06-26 15:08:31 +02:00 committed by GitHub
commit 2296b7c1d1
9 changed files with 260 additions and 84 deletions

View file

@ -7,11 +7,12 @@ 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
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

View file

@ -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

View file

@ -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
* Optional support for simpler TextField-based content editing
* Multisite support (posts can be visible in one or more Django sites on the
same project)
* Twitter cards, Open Graph and Google+ snippets meta tags
* Optional simpler TextField-based content editing
* Multisite (posts can be visible in one or more Django sites on the 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
* Support for django CMS 3.2+ Wizard
* Haystack index support
* Django sitemap framework
* django CMS 3.2+ Wizard
* 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/

View file

@ -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 %}

143
docs/channels.rst Normal file
View file

@ -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

View file

@ -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.

View file

@ -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`

View file

@ -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.

View file

@ -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.