Document that BASE_DIR is not a setting

[Eric Baumgartner]

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.

[Mariusz Felisiak]

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

[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 ​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 ​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.

[Jacob Walls]

Thanks. The first ​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. ​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.