Merge pull request #389 from aldryn/docs

Improved documentation

aldryn_newsblog/apps.py

@@ -4,4 +4,4 @@
 
 class AldrynNewsBlog(AppConfig):
     name = 'aldryn_newsblog'
-    verbose_name = 'Aldryn News and Blog'
+    verbose_name = 'Aldryn News & Blog'

aldryn_newsblog/cms_appconfig.py

@@ -142,8 +142,8 @@ def get_app_title(self):
         return getattr(self, 'app_title', _('untitled'))
 
     class Meta:
-        verbose_name = 'config'
-        verbose_name_plural = 'configs'
+        verbose_name = 'application configuration'
+        verbose_name_plural = 'application configurations'
 
 
 class NewsBlogConfigForm(AppDataForm):

aldryn_newsblog/migrations/0012_auto_20160503_1626.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+import aldryn_apphooks_config.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('aldryn_newsblog', '0011_auto_20160412_1622'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='newsblogconfig',
+            options={'verbose_name': 'application configuration', 'verbose_name_plural': 'application configurations'},
+        ),
+        migrations.AlterModelOptions(
+            name='newsblogconfigtranslation',
+            options={'default_permissions': (), 'verbose_name': 'application configuration Translation', 'managed': True},
+        ),
+        migrations.AlterField(
+            model_name='article',
+            name='app_config',
+            field=aldryn_apphooks_config.fields.AppHookConfigField(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig', help_text='When selecting a value, the form is reloaded to get the updated default'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogarchiveplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogarticlesearchplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogauthorsplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogcategoriesplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogfeaturedarticlesplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsbloglatestarticlesplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+        migrations.AlterField(
+            model_name='newsblogtagsplugin',
+            name='app_config',
+            field=models.ForeignKey(verbose_name='Apphook configuration', to='aldryn_newsblog.NewsBlogConfig'),
+        ),
+    ]

aldryn_newsblog/models.py

@@ -122,7 +122,7 @@ class Article(TranslatedAutoSlugifyMixin,
                                verbose_name=_('author'))
     owner = models.ForeignKey(settings.AUTH_USER_MODEL, verbose_name=_('owner'))
     app_config = AppHookConfigField(NewsBlogConfig,
-                                    verbose_name=_('app. config'))
+                                    verbose_name=_('Apphook configuration'))
     categories = CategoryManyToManyField('aldryn_categories.Category',
                                          verbose_name=_('categories'),
                                          blank=True)
@@ -255,7 +255,7 @@ class NewsBlogCMSPlugin(CMSPlugin):
     cmsplugin_ptr = models.OneToOneField(
         CMSPlugin, related_name='+', parent_link=True)
 
-    app_config = models.ForeignKey(NewsBlogConfig)
+    app_config = models.ForeignKey(NewsBlogConfig, verbose_name=_('Apphook configuration'))
 
     class Meta:
         abstract = True

docs/Makefile

@@ -61,6 +61,7 @@ help:
 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  spelling  to check for typos in documentation"
 
 clean:
 	rm -rf $(BUILDDIR)/*
@@ -191,3 +192,9 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+spelling:
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) _build/spelling
+	@echo
+	@echo "Check finished. Wrong words can be found in " \
+		"_build/spelling/output.txt."

docs/conf.py

@@ -12,9 +12,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# import sys
+import sys
 import os
-import aldryn_newsblog
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -51,10 +50,17 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = aldryn_newsblog.__version__
-# The full version, including alpha/beta/rc tags.
-release = aldryn_newsblog.__version__
+
+try:
+    import aldryn_newsblog
+except ImportError:
+    version = release = "undefined"
+else:
+    # The short X.Y version.
+    version = aldryn_newsblog.__version__
+    # The full version, including alpha/beta/rc tags.
+    release = aldryn_newsblog.__version__
+
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -269,3 +275,21 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+intersphinx_mapping = {'django-cms': ('http://docs.django-cms.org/en/develop/', None)}
+
+
+# -- Options for spelling checks ----------------------------------------------
+
+# Spelling check needs an additional module that is not installed by default.
+# Add it only if spelling check is requested so docs can be generated without it.
+if 'spelling' in sys.argv:
+    extensions.append("sphinxcontrib.spelling")
+
+# Spelling language.
+spelling_lang = 'en_GB'
+
+# Location of word list.
+spelling_word_list_filename = 'spelling_wordlist'
+
+spelling_ignore_pypi_package_names = True

docs/how-to/apphook_configurations.rst

@@ -0,0 +1,111 @@
+.. _multiple_news_sections:
+
+#############################
+Multiple news/weblog sections
+#############################
+
+Your project can host multiple independent news/weblog sections, each with their own items. For
+example, a company website might have a news section for publishing press releases, and a weblog for
+publishing more informal articles.
+
+To do this, you need to create a django CMS page for each news/weblog section, and add an apphook
+for Aldryn News & Blog to each of them. You will also need to create a separate apphook
+configuration for each of them - apphook configurations cannot be shared between apphook instances.
+
+.. note:
+
+    Creating a new News & Blog section on your site implies setting up a new apphook instance.
+    The apphook instance however doesn't actually do anything until a page has been set up with it.
+
+
+**********************************
+Creating a new News & Blog section
+**********************************
+
+The quickest way to do this is:
+
+* Create the new page.
+* In its *Advanced settings*, choose *Newsblog* in the *Application* field. A new field,
+  *Application configurations*, will appear immediately below it.
+* Add a new application configuration, by selecting the **+** icon.
+
+
+Fields
+======
+
+*Instance namespace* - a unique (and slug-like) name for this configuration. Note that this cannot be subsequently
+changed.
+
+*Application title* - A human-readable name for the configuration, that helps explain its purpose
+to the users of the system. For example, if this news section will publish press releases, call it
+*Press releases*. The name will be reflected in the django CMS toolbar when you're on that page.
+
+*Permalink type* - the format of canonical URLs for articles in this section.
+
+*Non-permalink-handling* - For convenience, the system can optionally resolve URLs that are not in
+the canonical format. For example, if the canonical URL is ``2016/11/27/man-bites-dog``, the URL
+``man-bites-dog`` can redirect to it. This behaviour is the default, but optional.
+
+*Prefix for template directories* - If you'd like this news section to use custom templates, create
+a set in a new directory. So for example, instead of using the default
+``aldryn_newsblog/article_list.html``, it will look for
+``aldryn_newsblog/custom-directory/article_list.html``.
+
+*Include in search index* - see :ref:`per_apphook_indexing`.
+
+Other fields are self-explanatory.
+
+Apphook configurations can also be created and edited in other ways:
+
+* from the Django Admin, in *Aldryn News & Blog* > *Application configuration*
+* from the option *Configure addon...* in the apphook's menu in the django CMS toolbar
+
+
+***********************************
+Access to application configuration
+***********************************
+
+Typically, you will not provide most content editors of your site with admin permissions to manage
+apphooks - this should be reserved for site managers.
+
+
+**************************************************
+Creating content in a specific News & Blog section
+**************************************************
+
+Articles
+========
+
+The section that a particular article is attached to is set in its *Application Configuration*
+field, in its *Advanced settings*. This can be changed once an article has been created, thus
+moving it from one section of a site to another.
+
+.. _section_secific_content:
+
+Section-specific shared content
+===============================
+
+In :ref:`shared_content`, we noted that you can use *Static placeholders* in your article templates
+``article_detail.html``, so that all articles can incorporate some boilerplate content (a typical
+example would be a list of social media links)::
+
+    {% static_placeholder "newsblog_social" %}
+
+Sometimes this is all you need, but if you are maintaining multiple News & Blog sections, you might
+not want *site-wide* shared content of this kind, but only *section-specific* shared content. For
+example, you might require one set of social media links for news pages aimed at your customers and
+another for pages aimed at your investors.
+
+In this case, you will need to override the default templates, which you can do at project level.
+You can remove the default ``{% static_placeholder %}`` altogether if you wish, or you can simply
+add new *apphook-configuration-aware* placeholder template tags where you need them. For example::
+
+    {% render_placeholder view.config.placeholder_detail_bottom %}
+
+Unlike static placeholder template tags, which can be added arbitrarily to your templates as you
+need them, these are standard ``PlaceholderFields``, defined in the `NewsBlogConfig model
+<https://github.com/aldryn/aldryn-newsblog/blob/master/aldryn_newsblog/cms_appconfig.py>`_.
+
+Several are defined there ready for you to use if you need them, and you advised to use them rather
+than amend that model to add your own (which will require forking the News & Blog code-base, and
+creating your own migrations for them.)

docs/how-to/basic_usage.rst

@@ -0,0 +1,95 @@
+.. _basic_usage:
+
+###################################
+Creating Aldryn News & Blog content
+###################################
+
+Before using Aldryn News & Blog, you need to :ref:`set up your django CMS project appropriately
+<django-cms-setup>` (in short, making sure that you have a page with a News & Blog apphook - this
+only takes a moment).
+
+This page is where your articles will be listed (see :ref:`multiple_news_sections` for multiple
+lists of articles).
+
+There are various different ways to create a new article:
+
+* From the django CMS toolbar, select **Create** then *New news/blog article*. This opens the
+  django CMS content wizard, providing a quick way to add new content.
+
+* If you're on a page with a News & Blog apphook, select *News & Blog* > *Add new article...* from
+  the django CMS toolbar.
+
+* Add a new article in the Django Admin, in the *Aldryn News & Blog* section.
+
+
+******
+Fields
+******
+
+Most of the fields for an article are self-explanatory, and they behave in logical ways. For
+example, setting the *Publishing date* in the future will publish the item automatically at that
+date/time.
+
+Note that items will not be published until the *Is published* option has been explicitly set (and the *Publishing
+date* has been reached).
+
+A *Featured* item will be given prominence in lists, such as on the home page of the news section.
+
+
+Meta Options
+============
+
+.. note:
+
+    Fields in the *Meta Options* section should override the default article title, description
+    (taken from the *Lead-in* field) and so on, **but are currently ignored**. This will be fixed
+    in a later revision.
+
+
+Advanced settings
+==================
+
+*Tags* are a set of optional free labels. Note that Tags, unlike most other fields, are not language-aware (i.e. the
+same set of tags is available across all languages). See the `Taggit documentation
+<https://django-taggit.readthedocs.io/en/latest/index.html>`_ for more.
+
+*Categories* offer a more formal taxonomy, managed by the `Aldryn Categories
+<http://aldryn-categories.readthedocs.org>`_ application.
+
+*Application configuration* allows you to select which list (if you have multiple Application Configurations) of
+news/weblog articles the article will be associated with.
+
+
+************
+Main content
+************
+
+Unless you used the *Content creation wizard* (the **Create** button) your new article will not
+have any content other than the *Lead-in*.
+
+The main content in an article is maintained in its *Newsblog Article Content* placeholder.
+
+To add content:
+
+* Select your (empty) article, for example from the News & Blog home page on your site.
+* By default, you will be in *Content* mode. Select *Structure* from the django CMS Toolbar.
+* Hit the **+** button to add a plugin to the *Newsblog Article Content* placeholder.
+* Typically, this will be a *Text* plugin; add some text and **Save**.
+
+When you switch back to *Content* mode, you'll see your full article.
+
+.. _shared_content:
+
+Shared content
+==============
+
+If you're using one of the default templates, you'll find that your article also contains another
+placeholder, called *Newsblog Social*. This is a *Static placeholder* - it's shared between all
+templates that contain it; in other words, between all News & Blog articles. If you add or change
+plugins in that placeholder, *all* your Aldryn News & Blog articles will display them.
+
+In this template, it's intended to be a convenient way for you to add social media links and buttons
+to all your News & Blog articles.
+
+See :ref:`section_secific_content` for more fine-grained control over content that's shared across
+articles.