[Django] #28102: Contradictory documentation about DIRS and TemplatesSetting

[Django]

#28102: Contradictory documentation about DIRS and TemplatesSetting
------------------------------------------------+------------------------
Reporter: Richard Eames | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.11
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
The documentation for the
[`DIRS`](https://docs.djangoproject.com/en/1.11/ref/templates/api/#the-
dirs-option) template setting states that
> This should be set to a list of strings that contain **full paths** to
your template directories

However, the documentation for the
[`TemplatesSetting`](https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#templatessetting)
class tells us:
> Adding the built-in widgets templates directory
(**django/forms/templates** or **django/forms/jinja2**) in `DIRS` of one
of your template engines.
That is, it says to add a relative path to the `DIRS` setting, which
contradicts the documentation for `DIRS`.

--
Ticket URL: <https://code.djangoproject.com/ticket/28102>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS
--------------------------------------+------------------------------------

Reporter: Richard Eames | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.11

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Tim Graham):

* easy: 0 => 1
* stage: Unreviewed => Accepted

Old description:

> The documentation for the
> [`DIRS`](https://docs.djangoproject.com/en/1.11/ref/templates/api/#the-
> dirs-option) template setting states that
> > This should be set to a list of strings that contain **full paths** to
> your template directories
>
> However, the documentation for the
> [`TemplatesSetting`](https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#templatessetting)
> class tells us:
> > Adding the built-in widgets templates directory
> (**django/forms/templates** or **django/forms/jinja2**) in `DIRS` of one
> of your template engines.
> That is, it says to add a relative path to the `DIRS` setting, which
> contradicts the documentation for `DIRS`.

New description:

The documentation for the
[https://docs.djangoproject.com/en/stable/ref/templates/api/#the-dirs-
option DIRS] template setting states that

> This should be set to a list of strings that contain **full paths** to
your template directories

However, the documentation for the

[https://docs.djangoproject.com/en/stable/ref/forms/renderers/#templatessetting
TemplatesSetting] class tells us:

> Adding the built-in widgets templates directory
(**django/forms/templates** or **django/forms/jinja2**) in `DIRS` of one
of your template engines.
That is, it says to add a relative path to the `DIRS` setting, which
contradicts the documentation for `DIRS`.

--

Comment:

The `TemplatesSetting` docs could be more explicit and include an example
of how to compute the full path to Django's built-in widget directories.
The same confusion was also raised in #28088.

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:1>

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS

-------------------------------------+-------------------------------------
Reporter: Richard Eames | Owner: Windson
Type: | yang
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Windson yang):

* owner: nobody => Windson yang
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:2>

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS
-------------------------------------+-------------------------------------
Reporter: Richard Eames | Owner: Windson
Type: | yang
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.11

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Windson yang):

I pull request here https://github.com/django/django/pull/8513 but failed
at doc test, any idea? Thanks.

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:3>

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS
-------------------------------------+-------------------------------------
Reporter: Richard Eames | Owner: Windson
Type: | yang
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.11

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Tim Graham):

* needs_better_patch: 0 => 1
* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:4>

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS
-------------------------------------+-------------------------------------
Reporter: Richard Eames | Owner: Windson
Type: | yang

Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.11
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Tim Graham <timograham@…>):

* status: assigned => closed
* resolution: => fixed

Comment:

In [changeset:"7f238097c0614707d6ee3fffbaf76f111b2fd38d" 7f23809]:
{{{
#!CommitTicketReference repository=""
revision="7f238097c0614707d6ee3fffbaf76f111b2fd38d"
Fixed #28102 -- Doc'd how to compute path to built-in widget template
directories.
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:5>

[Django]

#28102: Document how to put the full path of the built-in widget directories in
DIRS
-------------------------------------+-------------------------------------
Reporter: Richard Eames | Owner: Windson
Type: | yang
Cleanup/optimization | Status: closed

Component: Documentation | Version: 1.11

Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Tim Graham <timograham@…>):

In [changeset:"b373812b0bb4654e049ccf6a60e92a7e9f603a99" b373812b]:
{{{
#!CommitTicketReference repository=""
revision="b373812b0bb4654e049ccf6a60e92a7e9f603a99"
[1.11.x] Fixed #28102 -- Doc'd how to compute path to built-in widget
template directories.

Backport of 7f238097c0614707d6ee3fffbaf76f111b2fd38d from master
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/28102#comment:6>