[Django] #31387: Document BASE_DIR setting

[Django]

#31387: Document BASE_DIR setting
--------------------------------------------+------------------------
Reporter: Eric Baumgartner | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0
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 |
--------------------------------------------+------------------------
BASE_DIR appears to be an established setting. The default startapp
template defines it.

https://github.com/django/django/blob/master/django/conf/project_template/project_name/settings
.py-tpl

And third-party apps like django_extensions rely on BASE_DIR being set.

However, the main settings documentation page does not mention BASE_DIR at
all.

https://docs.djangoproject.com/en/3.0/ref/settings/

This led to confusion in the following case:

- Working with a legacy project that started around django 0.9.6 and has
never defined BASE_DIR, to no apparent ill effect.
- While using django_extensions, an exception is raised ('Settings' object
has no attribute 'BASE_DIR').
- Think: "Ok, that's fine, just need to define it, it's probably a newer
setting."
- Go to django docs to see the definition of BASE_DIR. Find nothing!
- Now confused. Is BASE_DIR unofficial? Why is django_extensions relying
on a non-standard setting?

It would be nice if BASE_DIR could be added to the settings documentation
to resolve this confusion.

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

[Django]

#31387: Document BASE_DIR setting.
----------------------------------+--------------------------------------

Reporter: Eric Baumgartner | Owner: nobody

Type: Uncategorized | Status: closed
Component: Documentation | Version: 3.0
Severity: Normal | Resolution: invalid

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

----------------------------------+--------------------------------------
Changes (by felixxm):

* status: new => closed
* resolution: => invalid

Comment:

`BASE_DIR` is not a setting. It's a constant set and used only by a
default `settings.py` template.

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

[Django]

#31387: Document BASE_DIR setting.
----------------------------------+--------------------------------------

Reporter: Eric Baumgartner | Owner: nobody

Type: Uncategorized | Status: closed
Component: Documentation | Version: 3.0
Severity: Normal | Resolution: invalid

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

----------------------------------+--------------------------------------
Comment (by kay):

> `BASE_DIR` is not a setting. It's a constant set and used only by a
default `settings.py` template.

In which case that should be documented.

I was just trying to look up how the Django documentation defines
`BASE_DIR` as I'm working on a project whose settings I need to detangle
and wanted to know what it should be "reset" to or what the recommended
default is.

A [https://docs.djangoproject.com/en/dev/search/?q=base_dir search for
`BASE_DIR` in the docs] only turned up six results, none of which actually
explain where it comes from, how to set it (or ''what to''), if it's a
built-in or something the user has to (ought to, may want to,...) set
themselves or similar.

It's mostly referenced in the context of other settings, making it appear
like its existence is considered a given (rather than, say, a stand-in for
`$SOMETHING`, or a convention).

The [https://docs.djangoproject.com/en/dev/howto/overriding-
templates/#:~:text=BASE_DIR%20/%20%22templates%22%5D%2C first search
result] points to a code example in which the variable is actually set,
though that first occurrence isn't highlighted for some reason, only the
latter is (where it's used to construct `TEMPLATES`' `"DIRS"`), so it may
be missed. The text below the box with the code sample contains another
mention – once more not highlighted – but doesn't go into it either.

The docs should spell out what `BASE_DIR` is, what it's used for,
expectations surrounding it etc. when it's first introduced.
--
Ticket URL: <https://code.djangoproject.com/ticket/31387#comment:2>

[Django]

#31387: Document BASE_DIR setting.
----------------------------------+--------------------------------------

Reporter: Eric Baumgartner | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0

Severity: Normal | Resolution:

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

----------------------------------+--------------------------------------
Changes (by kay):

* resolution: invalid =>
* status: closed => new

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

[Django]

#31387: Document that BASE_DIR is not a setting
-------------------------------------+-------------------------------------

Reporter: Eric Baumgartner | Owner: nobody

Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 3.0
Severity: Normal | Resolution: needsinfo

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Jacob Walls):

* resolution: => needsinfo

* status: new => closed

* summary: Document BASE_DIR setting. => Document that BASE_DIR is not a
setting
* type: Uncategorized => Cleanup/optimization

Comment:

Thanks. The first [https://docs.djangoproject.com/en/5.2/howto/overriding-
templates/#overriding-from-the-project-s-templates-directory search
result] says:

> The TEMPLATES setting and BASE_DIR will already exist if you created
your project using the default project template.

Accessing `settings.BASE_DIR` as if it's a setting is a misuse. I've seen
this before in third-party packages, e.g. [https://github.com/radusuciu
/django-
sqlfun/blob/12b4740ff02fa677f1ba97a12d4f2f0dd0c99314/sqlfun/utils.py#L160
django-sql-fun]. django-extensions defines it as their own setting.

We don't want to document it in settings, since it's not a setting. We
can't document every misuse.

Would you suggest we add a comment to the project template above where it
is defined? Closing as needsinfo pending a concrete suggestion.
--
Ticket URL: <https://code.djangoproject.com/ticket/31387#comment:4>