Startproject/app template documentation confusing

[sam@…]

For ​app/project templates I found the docs a little misleading when they say 'Any option passed to the startapp command' will be added to the context. This lead me to believe I could add arbitrary options to the command and pass them in to the context, which would make for some highly configurable app/project boilerplates. But, from looking at the ​source I gather by 'any options' they meant any valid options for the startapp/project commands.

Do you think it would be a cool feature to be able to pass any options or a file that defines additional context (maybe something consumable by ​ConfigParser)?

e.g.

bp-options.cfg:

[options]

css_dir=sass

js_dir=coffee

~/projects$ django-admin.py --template=/path/to/boilerplate --context=/path/to/bp-options.cfg myproject

I would definitely be willing to give this a shot if it is deemed useful.

Thanks!

[domguard]

Code and documentation patch

[domguard]

Indeed, the doc promise things that aren't happening in the code...

I've exchanged by email with sam, and another common proposal is just to have a command parameter that would accept additional template variables.
That's what the attached patch does, with a --add_context parameter
The proposed syntax (documented in the help of the command) is :

django-admin.py startproject --template=templ/folder/ --add_context=foo:bar,key:value mynewproject

# or abbreviated form

django-admin.py startproject --template=templ/folder/ -a foo:bar,key:value mynewproject

The string is parsed and key:values added to the template dict.

Also added the documention modification

[Sam Simmons <sam@…>]

Nice. That is much more simple than a config file.

[Jannis Leidel]

Having written the feature in question, I'm not convinced this is a good idea. Needs more discussion on the mailing list.

[Sam Simmons <sam@…>]

Replying to jezdez:

Having written the feature in question, I'm not convinced this is a good idea. Needs more discussion on the mailing list.

I hope you will at least keep the template option and continue to replace {{ project_name }}. This has already been useful for a django html5 boilerplate clone.

[domguard]

Discussion here : ​https://groups.google.com/forum/#!topic/django-developers/0aJMMZ7UjHk[[BR]]

jezdez suggested : make your startproject command by leveraging "make_option"

[domguard]

So this could be turned to a documentation bug to correct as the advertised feature does not exists !!

[Alex Tomkins]

If a design decision can't be made, the documentation bug should be fixed to prevent other users from assuming that the documentation is correct.

I've just been trying to use this non-existent functionality in a new 1.5 project.

[Aymeric Augustin]

Accepting as a documentation fix, the current wording trips up a lot of people (as seen on IRC and here).

[Tim Graham]

#18164 clarified startapp, but not startproject so I'll add that.

[Tim Graham <timograham@…>]

In 33503600b5562a2d0c0ba8d376a40432a4b30893:

Fixed #18277 - Clarified startproject documentation.

[Tim Graham <timograham@…>]

In ed3dd2759e7a95f3a0933782212dcb644c32a8c4:

[1.5.X] Fixed #18277 - Clarified startproject documentation.

Backport of 33503600b5 from master

[Tim Graham <timograham@…>]

In fbac080691760731319cefcb62617a9dd92af0af:

[1.4.X] Fixed #18277 - Clarified startproject documentation.

Backport of 33503600b5 from master