cookiecutter-django

cookiecutter-django copied to clipboard

Description

First, there wasn't a template for reporting a Documentation issue. I would have used it, if it existed. So, I selected an Improvement Suggestion. I hope this doesn't get ignored because I selected the wrong template. ;-) And, apologies for putting all of my text in this section. Rationale and Use case/Visualization don't make sense for Documentation.

The https://github.com/pydanny/cookiecutter-django/blob/master/docs/developing-locally.rst file has issues (multiple). I will put them all here.

1. You state that Python 3.6 is required. Should be Python 3.6+ (I assume you are not restricted to just 3.6)
2. Your Step 1 is: python3.6 -m venv Since you've already dictated python3.6 is required, and venv didn't appear until 3.3, it would not even be required for most. If it was, would it not typically be python3 not python3.6?
3. Your Step 2 assumes a Mac. Windows is \Scripts\activate.bat
4. Your Step 3: pip install -r requirements/local.txt ... this fails. Not sure what this is supposed to do.

I will stop here. I am a professional trainer and doc writer. I do this for a living. But, this is a project that interests me. So, I am willing to contribute. But, we need to discuss how best to do this. I am happy to contribute. Email me at [email protected] (most indirect path). Don't know if email skimmer read this stuff, but that email will get to me. If you want me to help/contribute, I have a more common email box I monitor.

Rationale

Use case(s) / visualization(s)

Thanks for reporting this issue. The page you mention could do with some improvements, yes.

1. We tests this project against 3.6 only. While it might work on 3.7, this isn't garanteed, so we rather not over promise. We could add a note about 3.7, but I'd rather upgrade the project to 3.7.
2. Users might have multiple version of python installed locally, so simply python3 might use the wrong one. I'm not sure I understand what you mean by "it would not even be required for most", maybe I missed your point.
3. Mac/Linux, yes. Unfortunately, I don't own a Windows machine... Instructions for Windows would be helpful, and if you feel like contributing, your help is welcome.
4. "It fails"... How? We might want to look into that separately if the logs indicate a bug.

As I said contributions are welcome, especially for documentation. Doesn't have to be a big re-write either.

(Related to #431)

Interesting, this is the first project in my limited python/django experience that has dictated a specific version of python, other than the python2/python3 schism. So, since this is a dictate of this project, there should be a note on how to do this. As my screenshot shows, I just type:

python --version

I don't even begin to know how to keep multiple versions of python. This would be something that should make the doc. I have seen the Mac/Windows/Linux, and that is one of the only (few?) places where it differs.

And, as far as the failure, the screenshot shows. There are other failures or inconsistencies, at least. Like, where/when do I install:

1. install django?
2. create the django project?
3. create the django app?
4. install cookiecutter and how?
5. invoke cookiecutter for the first time? run setup?
6. setting environment variables in Windows is different. Do I set them as system or user variables?
7. If I use a .env, do I put them in there instead of environment variables or both?
8. What else do I put in the .env?
9. You run a python manage.py migrate, should you have done a python manage.py makemigrations ... before doing the migrate?

I hope this helps. I am putting on my doc writer hat, and trying to make it better. Let me know how best to do it. Happy to keep doing this in issues (like this), but there may be a better way, Let me know.

I agree with @sawyer0413 that the usage section in the readme is missing in the docs. That is the starting point for this project. Installing cookiecutter is thus the first step.

When you choice use_docker[y] the only thing left is docker-compose -f local.yml up. That command sounds like a prayer to me.

The requirements directory is actually nested within the app/project name directory, so you'd either have to cd or include that in the path.

As someone who is newer to Django, there's a lot in this project that could use some explanation. For example, it looks like the cookiecutter installs a /users subdirectory within the named app, which has all the standard forms, models, urls, views files. One might be tempted to start adding code here, but I'm guessing the authors intent is that we create a new directory for our models??

I suppose I need to go order Two Scoops of Django to figure out what the design methodology is here.

@browniebroke any idea when 3.7 will be officially supported?

@untidy-hair good question, it's about time. I've opened a separate issue for it, if you feel like helping out: #2236

@browniebroke Great, thanks!

Do you have the intention to support the localisation of the content in the future, as we have with the Django official documentation?

It's not a priority, and realistically, we don't have the bandwidth to do so right now. It's hard enough to maintain in a single language, committing to localisation would definitely make it unsustainable, and it would quickly become out of date.