Tutorials need several changes

[otakucode]

I just started getting into django-cms today and decided to follow the tutorials from django-cms.org. This proved to be a difficult experience as the tutorials have several problems. Here are the ones I noticed (these notes are all specific to the tutorials for Django CMS 3.1):

On the Plugins tutorial:
After bringing in the 'polls' app from github, the tutorial directs the user to execute 'python manage.py migrate polls' in order to perform the necessary migration with South. For users using Django 1.7+, South is not used and the command will have no effect. The appropriate command for 1.7 users is 'python manage.py migrate'.

The tutorial refers to the 'polls application' but actually wants the user to work on the polls_plugin application which is misleading.

Near the end, South is again referenced. For Django 1.7 users, the correct commands would be 'python manage.py makemigrations' followed by 'python manage.py migrate'.

On the Apphooks tutorial:
This tutorial confusingly switches gears with no indication to the user from treating the polls app as a third-party tool to editing it directly. I was confused for a bit whether it was again simply failing to refer to the 'polls_plugin' application as previously, but it does indeed want the reader to delve into the source brought down from github and edit it.

The screenshot of the 'Advanced Settings' section of the Admin interface is incorrect, which isn't a big deal except that the shown window has an additional text field for naming the instance of the application which doesn't exist in Django CMS 3.1.

The reader is directed to create a child page under the Home page, but no instructions are given about how to do this. From the Admin home page, the user needs to click on 'Pages' in the 'django CMS' block, then use the Add Child button (which appears as a green '+' symbol) to the right of "Home". Once a child has been added, its Advanced Settings page can be accessed by clicking on the Page Settings button to the right of the child pages name. Its icon is a white sheet of paper with a blue pen lying on it. Once the Page Settings window is open, the option to switch to Advanced Settings is present in the lower left.

Near the end of this page of the tutorial the reader is directed to remove the previously added line from the base project urls.py which includes the urls of the polls application. If only this is done, the polls application will break. Attempting to enter it will result in a traceback which complains about 'polls' not being a registered namespace. This can be fixed by editing the index.html, detail.html, and results.html templates for the polls app. In those files, the 'url' template tag is used and, in a few places, passes in a value like 'polls:detail'. The 'polls:' prefix needs to be removed. In the case of index.html, 'polls:detail' is changed to just 'detail'. Likewise, the form action in detail.html needs to be similarly edited, as should a similar reference in results.html

Third Party Apps tutorial:
This entire tutorial is unusable for anyone using Python 3+. The third party application used, aldryn-blog, is not compatible with Python 3 and depends upon a component (Django-Select2) which is also not usable under Python 3. I found no indication on those projects GitHub pages that Python 3 support was being worked on. It would probably be best to simply find a different third-party application which supports Python 3 and remove the use of aldryn-blog. I am using Python 3 myself, so will have missed out on any problems with this segment of the tutorials.

Toolbar tutorial:
This tutorial does make it clear to the reader that they will be working with the polls app itself rather than the polls_plugin app... but it says "as in the previous tutorial". To be consistent with the changes to the Apphooks tutorial this will need to be minorly modified. The directly previous tutorial, the third party apps one, actually didn't refer to the polls or polls_plugin apps.

Menu tutorial:
When editing cms_app.py to add in the reference to the menu, the files imports need to be modified to add something like "from .menu import PollsMenu". The instructions as given will generate a Name Error exception due to PollsMenu not being resolved.

Since I am brand new to Django CMS, I didn't want to just dive in and submit pull requests for changes to the tutorials, but I am more than willing to make the edits I feel are necessary if others agree that I've not proposed something weird or wrong. I won't be able to modify the third party apps tutorial, though, because I simply am not familiar with any alternative third party app which could be used.

[yakky]

Such a comprehensive review! Thanks for taking the time to check all this!

[evildmp]

Thanks, that is excellent feedback. Are you interested in helping patch the documentation to address these issues? We're always extremely glad to have such help.

[fallenflint]

Hello. I've found few little bugs in code examples. Not worth opening entire issue, so I just add it here:
http://django-cms.readthedocs.org/en/latest/how_to/extending_page_title.html#simplified-toolbar-api
both examples in section "Simplified toolbar api" lacks of from cms.toolbar_pool import toolbar_pool, so code throws NameError.

However, consequent examples has needed import
from cms.toolbar_pool import toolbar_pool

[amitbend]

otakucode you helped alot,
I started learning and had so much trouble.
thanks

[evildmp]

Thanks for the report. In fact the tutorial was thoroughly rewritten some time ago and all these issues have been addressed.