Visitar URL original
Improve installation instructions · Issue #265 · feincms/feincms · GitHub
Skip to content

Improve installation instructions #265

Open
Open
Improve installation instructions#265
Labels
documentation
Milestone
1.7

Description

@gw0
gw0
opened on Apr 1, 2012

The documentation for installation instructions and configuration (http://readthedocs.org/docs/feincms-django-cms/en/latest/installation.html) is not obvious and well documentet on how to get a simple basic FeinCMS to work.

My steps and thoughts (that could discourage some users) when reading the page and installing were:

  • pip install django or easy_install django is not explicitly mentioned in the example, so it seems I must read all the boring text
  • then a prerequisite is django, lets install it
  • then install feincms
  • hm, django-mptt seems like another prerequisite, but why isn't it listed next to django (and also why isn't it automatically installed as a dependent Python module when using pip)
  • then here is a list of optional packages to install
  • lets prepare a django project: django-admin.py startproject test
  • edit settings.py and add feincms and feincms.modules.page to INSTALLED_APPS and configure static directories
  • ./manage.py syncdb
  • ./manage.py runserver gives error about mptt
  • add mptt to settings.py (weird they didn't explicitly mention it)
  • ./manage.py runserver
  • open browser and see a "Error: 'PageAdmin.fieldsets[0][1]['fields']' refers to field 'template_key' that is missing from the form" error (https://groups.google.com/group/django-feincms/browse_thread/thread/263ea8c72e737b5a)
  • oh, lets check FAQ (http://readthedocs.org/docs/feincms-django-cms/en/latest/faq.html), but it isn't there, google also doesn't find much
  • lets see if there are better instructions in the source repository and checking out quickstart.sh, testing it and figuring out what needs to be done
  • after some time figuring out that the Page.register_templates and similar are the essential to making it work, finding instructions this on the page module documentation
  • now there are some Image related errors, lets install PIL although it is mentioned as required
  • finally it works with some deprecation warnings
  • wondering how many people just gave up because of the incomplete and too complicated installation instructions

Therefore my suggestion would be to include it in QUICKSTART.rst and on http://readthedocs.org/docs/feincms-django-cms/en/latest/installation.html examples of instructions to getting a simple basic most common FeinCMS installation up. This means in Installation chapter things like:

# optionally prepare an isolated virtual environment:
virtualenv --no-site-packages mycms
cd mycms
source bin/activate
# install dependencies:
pip install django django-mptt pil
# other optional dependencies:
pip install lxml django-tagging feedparser
# install feincms
pip install feincms

And later in the Configuration chapter:

Create file modules.py directly in the project directory or in an app and put in it Page.register_templates() like on http://readthedocs.org/docs/feincms-django-cms/en/latest/page.html .

In settings.py configure static files and add apps:

INSTALLED_APPS = (
    ...
    'feincms',
    'feincms.module.page',
    #'feincms.module.blog',
    #'feincms.module.medialibrary',
    'mptt',
    'name-of-your-project-or-app-with-register_templates',
    ...
)

To initialize:

./manage.py syncdb
./manage.py collectstatic

This instructions should also be same in QUICKSTART.rst.

The error "Error: 'PageAdmin.fieldsets[0][1]['fields']' refers to field 'template_key' that is missing from the form" and the exception on missing PIL module should be explicitly mentioned on the FAQ page (http://readthedocs.org/docs/feincms-django-cms/en/latest/faq.html).

In my opinion this would have a very positive effect on the user experience of new potential users that want to configure their Django installations from scratch.

Activity

  1. matthiask commented on Apr 4, 2012

    @matthiask
    matthiask
    on Apr 4, 2012
    Member

    Thanks for there comments, they are very helpful. If nobody beats me to it I'll rework the installation instructions before the next release following your suggestions.

  2. mjtamlyn commented on Apr 28, 2012

    @mjtamlyn
    mjtamlyn
    on Apr 28, 2012
    Contributor

    It struck me reading this that perhaps two versions of the installation instructions are necessary - one for those who are familiar with installing a variety of django packages and configuring them, and one for those who aren't familiar with django at all. Whilst I don't think we should rewrite a django tutorial, it's not unreasonable that some users will come to feincms first, and just see django as a requirement. It would be good if those users were not put off.

    With the advent of configurable project templates in Django, perhaps it would be beneficial to provide a small example of this for FeinCMS.

    Also, this error is the worst. 'PageAdmin.fieldsets[0][1]['fields']' refers to field 'template_key'

  3. ghost assigned
    sbaechler
    on May 8, 2012

  4. sbaechler commented on May 8, 2012

    @sbaechler
    sbaechler
    on May 8, 2012
    Contributor

    We are working on a quick install script that sets up a working FeinCMS project. I'm also currently writing a tutorial on how to set up FeinCMS and Elephantblog.
    We hope that everything will be ready for DjangoCon.

  5. matthiask commented on May 9, 2012

    @matthiask
    matthiask
    on May 9, 2012
    Member

    Marc: You are raising a good point. I still think we should point newcomers to the Django tutorial instead of trying to redo the awesome work of the Django devs. After all you really have to understand a good part of Django to get a smooth FeinCMS experience.

    Also, I totally agree about the template_key error. I did not manage to trigger this error anymore except with a contrived example, and that would be by using Page.register_regions instead of Page.register_templates (If you didn't know this was possible please forget about it right now, again.)

    :-)

  6. mjtamlyn commented on May 9, 2012

    @mjtamlyn
    mjtamlyn
    on May 9, 2012
    Contributor

    I agree that duplicating Django tutorials would be pretty silly, but I definitely like the idea of providing an example project layout utilising the new django 1.4 template project stuff.

    I never seem to manage to trigger the template_key error by actually doing anything in FeinCMS, it somehow manages to trigger by doing something else wrong in a totally unrelated place - although I've seen it much less often with the 1.5 branch.

  7. ghost assigned
    matthiask
    on Jun 14, 2012

  8. sbaechler commented on Sep 6, 2012

    @sbaechler
    sbaechler
    on Sep 6, 2012
    Contributor

    I started writing an expansive tutorial a few months ago specifically for users that are new to Django. The only requirement should be the Django tutorial.

    I managed to finish the first two chapters (out of seven) to the point where the FeinCMS admin is working. It's about 13 pages on Google Docs so far.

    Because I started my studies next to my job here I won't be able to spend more time on it in the near future. If someone would like to take it over, please contact me.

  9. matthiask
    added a commit that references this issue on Oct 18, 2013

    Automatically install dependencies when using setup.py

    6994748
  10. matthiask
    removed their assignment
    on Jul 11, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentation

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions