Code

Opened 2 years ago

Closed 16 months ago

Last modified 16 months ago

#18277 closed Bug (fixed)

Startproject/app template documentation confusing

Reported by: sam@… Owned by: quinode
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 quinode 2 years ago.
Code and documentation patch

Download all attachments as: .zip

Change History (14)

Changed 2 years ago by quinode

Code and documentation patch

comment:1 Changed 2 years ago by quinode

  • Cc dguardiola@… added
  • Component changed from Documentation to Core (Management commands)
  • Has patch set
  • Needs documentation unset
  • Needs tests unset
  • Owner changed from nobody to quinode
  • Patch needs improvement unset
  • Status changed from new to assigned

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 2 years ago by Sam Simmons <sam@…>

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

comment:3 Changed 2 years ago by jezdez

  • Triage Stage changed from Unreviewed to Design decision needed

comment:4 follow-up: Changed 2 years ago by jezdez

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 2 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 2 years ago by quinode

  • Triage Stage changed from Design decision needed to Someday/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 2 years ago by quinode (next)

comment:7 Changed 2 years ago by quinode

  • Triage Stage changed from Someday/Maybe to Design decision needed
  • Type changed from New feature to Bug

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

comment:8 Changed 16 months ago by aptomkins

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 16 months ago by aaugustin

  • Component changed from Core (Management commands) to Documentation
  • Triage Stage changed from Design decision needed to Accepted

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

comment:10 Changed 16 months ago by timo

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

comment:11 Changed 16 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In 33503600b5562a2d0c0ba8d376a40432a4b30893:

Fixed #18277 - Clarified startproject documentation.

comment:12 Changed 16 months ago by Tim Graham <timograham@…>

In ed3dd2759e7a95f3a0933782212dcb644c32a8c4:

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

Backport of 33503600b5 from master

comment:13 Changed 16 months ago by Tim Graham <timograham@…>

In fbac080691760731319cefcb62617a9dd92af0af:

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

Backport of 33503600b5 from master

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.