Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#18277 closed Bug (fixed)

Startproject/app template documentation confusing

Reported by: sam@… Owned by: domguard
Component: Documentation Version: 1.4
Severity: Normal Keywords: startproject startapp template
Cc: dguardiola@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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!

Attachments (1)

ticket18277.diff (3.5 KB) - added by domguard 4 years ago.
Code and documentation patch

Download all attachments as: .zip

Change History (14)

Changed 4 years ago by domguard

Attachment: ticket18277.diff added

Code and documentation patch

comment:1 Changed 4 years ago by domguard

Cc: dguardiola@… added
Component: DocumentationCore (Management commands)
Has patch: set
Needs documentation: unset
Needs tests: unset
Owner: changed from nobody to domguard
Patch needs improvement: unset
Status: newassigned

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

comment:2 Changed 4 years ago by Sam Simmons <sam@…>

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

comment:3 Changed 4 years ago by Jannis Leidel

Triage Stage: UnreviewedDesign decision needed

comment:4 Changed 4 years ago by Jannis Leidel

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

comment:5 in reply to:  4 Changed 4 years ago by 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.

comment:6 Changed 4 years ago by domguard

Triage Stage: Design decision neededSomeday/Maybe

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

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

Version 0, edited 4 years ago by domguard (next)

comment:7 Changed 4 years ago by domguard

Triage Stage: Someday/MaybeDesign decision needed
Type: New featureBug

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

comment:8 Changed 4 years ago by 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.

comment:9 Changed 4 years ago by Aymeric Augustin

Component: Core (Management commands)Documentation
Triage Stage: Design decision neededAccepted

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

comment:10 Changed 3 years ago by Tim Graham

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

comment:11 Changed 3 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 33503600b5562a2d0c0ba8d376a40432a4b30893:

Fixed #18277 - Clarified startproject documentation.

comment:12 Changed 3 years ago by Tim Graham <timograham@…>

In ed3dd2759e7a95f3a0933782212dcb644c32a8c4:

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

Backport of 33503600b5 from master

comment:13 Changed 3 years ago by Tim Graham <timograham@…>

In fbac080691760731319cefcb62617a9dd92af0af:

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

Backport of 33503600b5 from master

Note: See TracTickets for help on using tickets.
Back to Top