S3 documentation and suggested configuration

Issue #140 open
Eleni Lixourioti
created an issue

There was another issue with a similar title, but this one is a bit more general.

There are 2 backends described in the first paragraph but they're almost completely hidden in plain text and given as paths instead of modules (foo/bar/buzz.py vs foo.var.buzz)(?!). The same "path-centric" logic is also applied right underneath, when describing where to find the the backend module. Having "libs.storages.S3Storage.S3Storage" as the first example is at least confusing since it doesn't apply to 99% of users. People who would install the storage in a random location like that either: a) know what they're doing very well, in which case they don't need to be told how to load the module as it's like every other module or b) they have no idea how to install packages and where, in which case they need help with that rather than with settings. The installation instructions advise installing from pypi, so all this seems unnecessary.

Someone going for the python s3 bindings will also probably find it impossible to make things work, since there is no obvious way to get them anymore. Amazon just recommends boto these days. If you do regardless try to use the s3 backend without knowing you need to install anything and the bindings are missing, you then get an error message ImproperlyConfigured: Could not load amazon's S3 bindings. See "http://developer.amazonwebservices.com/connect/entry.jspa?externalID=134"
which is also a broken link and more confusing than helpful.

I think setting up everything for s3 should be a simple process for the average user. It's better to have a basic configuration example that is "known to work for most people" first thing. Then you could go into more detail on various options.

Finally, the "Tests" section doesn't feel like it has to do with testing at all which is also confusing, this would be a the section where you would either give instructions to people wanting to extend django-storage and write unit tests, or any quirky behaviour your storage has that might affect people's tests. I believe it should be called something like "Examples".

I am happy to write a pull request for the above myself. I do not know the library well and maybe I'm missing something so I don't want to write it and leave it sitting in pull requests, which is why I created this issue first to see if people agree/disagree with the above.

Comments (5)

  1. David Larlet repo owner

    Hi Eleni,

    Please do not hesitate to improve the documentation! That's very difficult to be able to help beginners once you know the lib so your feedback is really appreciated and highly valuable to the community :)


  2. Log in to comment