django-pipeline icon indicating copy to clipboard operation
django-pipeline copied to clipboard

Published 20 hours ago • verified publisher icon jazzband

Documentation could be newcomer-friendlier

Open metakermit opened this issue 6 years ago • 2 comments

Hi, I've first tried django-pipeline (after using django-compressor in the past) and I had some trouble getting everything configured correctly. Here's some well-intended feedback on the parts I found confusing:

  • no "quick start" section – it would be nice to have a section that shows you how to fully configure a working django-pipeline setup with typical options e.g. Sass, autoprefixer & JS, a vendor folder for some libraries etc. After reading 4 sections (Installation, Configuration, Usage, Compilers), I was still a bit unsure how to use django-pipeline. I found this video to be much clearer, but it's outdated now
  • no example code – since there are a lot of things to consider (django-pipeline isn't exactly a drop-in one-liner addition to a Django project), it would be great if you had a minimal example Django app project that correctly configures everything. As it is now, I had to do a lot of jumping between different sections to assemble something that works.
  • unclear Usage section – at first I didn't get that the actual stylesheet/JS invocation {% stylesheet 'colors' %} shouldn't go to the beginning of a template, but inside the <head>, <body> etc. Why not give some example html here to make this immediately obvious? Also, I found this example code very far away from where 'colors' were defined.
  • the "Upgrading from…" stuff in the very beginning looks a bit out of place. Perhaps a separate section and just linking to it?
  • I feel like I shot myself in the foot too easily by misconfiguring something and getting errors like:
django.core.exceptions.SuspiciousFileOperation: The joined path (/) is located outside of the base path component (/Users/kermit/code/posterbat/.venv/lib/python3.7/site-packages/django/contrib/admin/static)

Seems I caused this error by forgetting the trailing comma (maybe using a list here would be better):

'source_filenames': (
    'promote/promote.scss',
)

Anyway, that's it for now. I hope some of these points could motivate a few documentation-improving PRs 🙂

metakermit avatar Nov 01 '18 22:11 metakermit

Thanks for this issue, I've been scratching my head trying to figure out what the hell was causing django.core.exceptions.SuspiciousFileOperation on my end lol

tedmdelacruz avatar Jun 28 '19 06:06 tedmdelacruz

oh my!! such a silly mistake. I wasted 2 hours in digging up insides of Django

sar009 avatar Oct 01 '19 16:10 sar009