From 4eb5e4ee4fe097986df839b11efb69b6bb9db00f Mon Sep 17 00:00:00 2001 From: Nick Pope Date: Thu, 30 Apr 2020 11:12:05 +0100 Subject: [PATCH] [3.1.x] Used :envvar: role and .. envvar:: directive in various docs. Backport of fbdb032de266ba5f82e061ab204f6c622889d563 from master --- docs/faq/usage.txt | 6 ++-- docs/howto/deployment/wsgi/uwsgi.txt | 2 +- .../writing-code/coding-style.txt | 4 +-- .../contributing/writing-code/unit-tests.txt | 10 +++--- .../contributing/writing-documentation.txt | 4 +++ docs/intro/tutorial02.txt | 4 +-- docs/ref/checks.txt | 2 +- docs/ref/contrib/gis/geos.txt | 2 +- docs/ref/django-admin.txt | 29 ++++++++++------ docs/releases/1.2.txt | 6 ++-- docs/releases/1.4.txt | 2 +- docs/releases/2.2.1.txt | 3 +- docs/releases/3.0.1.txt | 2 +- docs/topics/async.txt | 4 ++- docs/topics/settings.txt | 34 +++++++++---------- 15 files changed, 65 insertions(+), 49 deletions(-) diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt index 0145a580fd..f95ca11174 100644 --- a/docs/faq/usage.txt +++ b/docs/faq/usage.txt @@ -2,12 +2,12 @@ FAQ: Using Django ================= -Why do I get an error about importing DJANGO_SETTINGS_MODULE? -============================================================= +Why do I get an error about importing :envvar:`DJANGO_SETTINGS_MODULE`? +======================================================================= Make sure that: -* The environment variable DJANGO_SETTINGS_MODULE is set to a +* The environment variable :envvar:`DJANGO_SETTINGS_MODULE` is set to a fully-qualified Python module (i.e. "mysite.settings"). * Said module is on ``sys.path`` (``import mysite.settings`` should work). diff --git a/docs/howto/deployment/wsgi/uwsgi.txt b/docs/howto/deployment/wsgi/uwsgi.txt index 561602ff34..43cfdf3b93 100644 --- a/docs/howto/deployment/wsgi/uwsgi.txt +++ b/docs/howto/deployment/wsgi/uwsgi.txt @@ -77,7 +77,7 @@ The Django-specific options here are: path -- i.e., the directory containing the ``mysite`` package. * ``module``: The WSGI module to use -- probably the ``mysite.wsgi`` module that :djadmin:`startproject` creates. -* ``env``: Should probably contain at least ``DJANGO_SETTINGS_MODULE``. +* ``env``: Should probably contain at least :envvar:`DJANGO_SETTINGS_MODULE`. * ``home``: Optional path to your project virtualenv. Example ini configuration file:: diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 43db31501e..6793dde79e 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -283,8 +283,8 @@ at the top level (i.e. evaluated when the module is imported). The explanation for this is as follows: Manual configuration of settings (i.e. not relying on the -``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as -follows:: +:envvar:`DJANGO_SETTINGS_MODULE` environment variable) is allowed and possible +as follows:: from django.conf import settings diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 21bdf00664..deaa5a0b19 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -105,8 +105,8 @@ The remainder of this documentation shows commands for running tests without ``tox``, however, any option passed to ``runtests.py`` can also be passed to ``tox`` by prefixing the argument list with ``--``, as above. -Tox also respects the ``DJANGO_SETTINGS_MODULE`` environment variable, if set. -For example, the following is equivalent to the command above: +Tox also respects the :envvar:`DJANGO_SETTINGS_MODULE` environment variable, if +set. For example, the following is equivalent to the command above: .. code-block:: console @@ -156,7 +156,7 @@ those for ``contrib.postgres``, are specific to a particular database backend and will be skipped if run with a different backend. To run the tests with different settings, ensure that the module is on your -``PYTHONPATH`` and pass the module with ``--settings``. +:envvar:`PYTHONPATH` and pass the module with ``--settings``. The :setting:`DATABASES` setting in any test settings module needs to define two databases: @@ -495,8 +495,8 @@ test failures. You can adjust this behavior with the ``--parallel`` option: $ ./runtests.py basic --parallel=1 -You can also use the ``DJANGO_TEST_PROCESSES`` environment variable for this -purpose. +You can also use the :envvar:`DJANGO_TEST_PROCESSES` environment variable for +this purpose. Tips for writing tests ====================== diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index bd9d0e9495..82f918f921 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -246,6 +246,10 @@ documentation: * Use :rst:role:`:mimetype:` to refer to a MIME Type unless the value is quoted for a code example. +* Use :rst:role:`:envvar:` to refer to an environment variable. You may + also need to define a reference to the documentation for that environment + variable using :rst:dir:`.. envvar:: `. + Django-specific markup ====================== diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index 42e3ccd110..8ee3ec8159 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -378,8 +378,8 @@ API Django gives you. To invoke the Python shell, use this command: $ python manage.py shell We're using this instead of simply typing "python", because :file:`manage.py` -sets the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives Django -the Python import path to your :file:`mysite/settings.py` file. +sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable, which gives +Django the Python import path to your :file:`mysite/settings.py` file. Once you're in the shell, explore the :doc:`database API `:: diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 37a3a572c9..5d10482b0b 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -111,7 +111,7 @@ Asynchronous support The following checks verify your setup for :doc:`/topics/async`: -* **async.E001**: You should not set the ``DJANGO_ALLOW_ASYNC_UNSAFE`` +* **async.E001**: You should not set the :envvar:`DJANGO_ALLOW_ASYNC_UNSAFE` environment variable in deployment. This disables :ref:`async safety protection `. diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index cfb207288f..74de7b255c 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -32,7 +32,7 @@ features include: in Python using ``ctypes``. * Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects may be used outside of a Django project/application. In other words, - no need to have ``DJANGO_SETTINGS_MODULE`` set or use a database, etc. + no need to have :envvar:`DJANGO_SETTINGS_MODULE` set or use a database, etc. * Mutability: :class:`GEOSGeometry` objects may be modified. * Cross-platform and tested; compatible with Windows, Linux, Solaris, and macOS platforms. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 35d6c04b30..78efcf0afb 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -127,8 +127,8 @@ Activates some additional checks that are only relevant in a deployment setting. You can use this option in your local development environment, but since your local development settings module may not have many of your production settings, you will probably want to point the ``check`` command at a different settings -module, either by setting the ``DJANGO_SETTINGS_MODULE`` environment variable, -or by passing the ``--settings`` option:: +module, either by setting the :envvar:`DJANGO_SETTINGS_MODULE` environment +variable, or by passing the ``--settings`` option:: django-admin check --deploy --settings=production_settings @@ -942,8 +942,10 @@ more robust change detection, and a reduction in power usage. Django supports .. admonition:: Watchman timeout + .. envvar:: DJANGO_WATCHMAN_TIMEOUT + The default timeout of ``Watchman`` client is 5 seconds. You can change it - by setting the ``DJANGO_WATCHMAN_TIMEOUT`` environment variable. + by setting the :envvar:`DJANGO_WATCHMAN_TIMEOUT` environment variable. .. _Watchman: https://facebook.github.io/watchman/ .. _pywatchman: https://pypi.org/project/pywatchman/ @@ -1431,13 +1433,15 @@ Enables :ref:`SQL logging ` for failing tests. If .. django-admin-option:: --parallel [N] +.. envvar:: DJANGO_TEST_PROCESSES + Runs tests in separate parallel processes. Since modern processors have multiple cores, this allows running tests significantly faster. By default ``--parallel`` runs one process per core according to :func:`multiprocessing.cpu_count()`. You can adjust the number of processes either by providing it as the option's value, e.g. ``--parallel=4``, or by -setting the ``DJANGO_TEST_PROCESSES`` environment variable. +setting the :envvar:`DJANGO_TEST_PROCESSES` environment variable. Django distributes test cases — :class:`unittest.TestCase` subclasses — to subprocesses. If there are fewer test cases than configured processes, Django @@ -1614,6 +1618,8 @@ Example usage:: .. django-admin:: createsuperuser +.. envvar:: DJANGO_SUPERUSER_PASSWORD + This command is only available if Django's :doc:`authentication system ` (``django.contrib.auth``) is installed. @@ -1623,9 +1629,9 @@ programmatically generate superuser accounts for your site(s). When run interactively, this command will prompt for a password for the new superuser account. When run non-interactively, you can provide -a password by setting the ``DJANGO_SUPERUSER_PASSWORD`` environment variable. -Otherwise, no password will be set, and the superuser account will not be able -to log in until a password has been manually set for it. +a password by setting the :envvar:`DJANGO_SUPERUSER_PASSWORD` environment +variable. Otherwise, no password will be set, and the superuser account will +not be able to log in until a password has been manually set for it. In non-interactive mode, the :attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD` and required @@ -1758,7 +1764,7 @@ allows for the following options: .. django-admin-option:: --pythonpath PYTHONPATH Adds the given filesystem path to the Python `import search path`_. If this -isn't provided, ``django-admin`` will use the ``PYTHONPATH`` environment +isn't provided, ``django-admin`` will use the :envvar:`PYTHONPATH` environment variable. This option is unnecessary in ``manage.py``, because it takes care of setting @@ -1774,7 +1780,8 @@ Example usage:: Specifies the settings module to use. The settings module should be in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, -``django-admin`` will use the ``DJANGO_SETTINGS_MODULE`` environment variable. +``django-admin`` will use the :envvar:`DJANGO_SETTINGS_MODULE` environment +variable. This option is unnecessary in ``manage.py``, because it uses ``settings.py`` from the current project by default. @@ -1844,6 +1851,8 @@ Extra niceties Syntax coloring --------------- +.. envvar:: DJANGO_COLORS + The ``django-admin`` / ``manage.py`` commands will use pretty color-coded output if your terminal supports ANSI-colored output. It won't use the color codes if you're piping the command's output to @@ -1865,7 +1874,7 @@ ships with three color palettes: * ``nocolor``, which disables syntax highlighting. -You select a palette by setting a ``DJANGO_COLORS`` environment +You select a palette by setting a :envvar:`DJANGO_COLORS` environment variable to specify the palette you want to use. For example, to specify the ``light`` palette under a Unix or OS/X BASH shell, you would run the following at a command prompt:: diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index d735d22f74..0b761138e6 100644 --- a/docs/releases/1.2.txt +++ b/docs/releases/1.2.txt @@ -321,9 +321,9 @@ and calculated values can be displayed alongside editable fields. Customizable syntax highlighting -------------------------------- -You can now use a ``DJANGO_COLORS`` environment variable to modify or disable -the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting -`. +You can now use a :envvar:`DJANGO_COLORS` environment variable to modify or +disable the colors used by ``django-admin.py`` to provide :ref:`syntax +highlighting `. Syndication feeds as views -------------------------- diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 9a802ac370..aa760cc4c9 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -1257,7 +1257,7 @@ needed with the new ``manage.py`` and default project layout. This function was never documented or part of the public API, but it was widely recommended for use in setting up a "Django environment" for a user script. -These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` +These uses should be replaced by setting the :envvar:`DJANGO_SETTINGS_MODULE` environment variable or using :func:`django.conf.settings.configure`. ``django.core.management.execute_manager`` diff --git a/docs/releases/2.2.1.txt b/docs/releases/2.2.1.txt index 6438e7fc37..4eb4e18fe9 100644 --- a/docs/releases/2.2.1.txt +++ b/docs/releases/2.2.1.txt @@ -58,7 +58,8 @@ Bugfixes * Increased the default timeout when using ``Watchman`` to 5 seconds to prevent falling back to ``StatReloader`` on larger projects and made it customizable - via the ``DJANGO_WATCHMAN_TIMEOUT`` environment variable (:ticket:`30361`). + via the :envvar:`DJANGO_WATCHMAN_TIMEOUT` environment variable + (:ticket:`30361`). * Fixed a regression in Django 2.2 that caused a crash when migrating permissions for proxy models if the target permissions already existed. For diff --git a/docs/releases/3.0.1.txt b/docs/releases/3.0.1.txt index 1c32528304..a0fb1f560c 100644 --- a/docs/releases/3.0.1.txt +++ b/docs/releases/3.0.1.txt @@ -28,7 +28,7 @@ Bugfixes * Fixed a regression in Django 3.0 by restoring the ability to use Django inside Jupyter and other environments that force an async context, by adding an option to disable :ref:`async-safety` mechanism with - ``DJANGO_ALLOW_ASYNC_UNSAFE`` environment variable (:ticket:`31056`). + :envvar:`DJANGO_ALLOW_ASYNC_UNSAFE` environment variable (:ticket:`31056`). * Fixed a regression in Django 3.0 where ``RegexPattern``, used by :func:`~django.urls.re_path`, returned positional arguments to be passed to diff --git a/docs/topics/async.txt b/docs/topics/async.txt index 99b7f06113..09a4775966 100644 --- a/docs/topics/async.txt +++ b/docs/topics/async.txt @@ -120,6 +120,8 @@ mode if you have asynchronous code in your project. Async safety ============ +.. envvar:: DJANGO_ALLOW_ASYNC_UNSAFE + Certain key parts of Django are not able to operate safely in an async environment, as they have global state that is not coroutine-aware. These parts of Django are classified as "async-unsafe", and are protected from execution in @@ -146,7 +148,7 @@ if the requirement is forced on you by an external environment, such as in a Jupyter_ notebook. If you are sure there is no chance of the code being run concurrently, and you *absolutely* need to run this sync code from an async context, then you can disable the warning by setting the -``DJANGO_ALLOW_ASYNC_UNSAFE`` environment variable to any value. +:envvar:`DJANGO_ALLOW_ASYNC_UNSAFE` environment variable to any value. .. warning:: diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index 7a420b6777..d09ba08b10 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -40,10 +40,10 @@ Designating the settings .. envvar:: DJANGO_SETTINGS_MODULE When you use Django, you have to tell it which settings you're using. Do this -by using an environment variable, ``DJANGO_SETTINGS_MODULE``. +by using an environment variable, :envvar:`DJANGO_SETTINGS_MODULE`. -The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g. -``mysite.settings``. Note that the settings module should be on the +The value of :envvar:`DJANGO_SETTINGS_MODULE` should be in Python path syntax, +e.g. ``mysite.settings``. Note that the settings module should be on the Python `import search path`_. .. _import search path: https://www.diveinto.org/python3/your-first-python-program.html#importsearchpath @@ -170,10 +170,10 @@ a convention. .. _settings-without-django-settings-module: -Using settings without setting ``DJANGO_SETTINGS_MODULE`` -========================================================= +Using settings without setting :envvar:`DJANGO_SETTINGS_MODULE` +=============================================================== -In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE`` +In some cases, you might want to bypass the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. For example, if you're using the template system by itself, you likely don't want to have to set up an environment variable pointing to a settings module. @@ -234,19 +234,19 @@ defaults, so you must specify a value for every possible setting that might be used in that code you are importing. Check in ``django.conf.settings.global_settings`` for the full list. -Either ``configure()`` or ``DJANGO_SETTINGS_MODULE`` is required ----------------------------------------------------------------- +Either ``configure()`` or :envvar:`DJANGO_SETTINGS_MODULE` is required +---------------------------------------------------------------------- -If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you -*must* call ``configure()`` at some point before using any code that reads -settings. +If you're not setting the :envvar:`DJANGO_SETTINGS_MODULE` environment +variable, you *must* call ``configure()`` at some point before using any code +that reads settings. -If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``, -Django will raise an ``ImportError`` exception the first time a setting -is accessed. +If you don't set :envvar:`DJANGO_SETTINGS_MODULE` and don't call +``configure()``, Django will raise an ``ImportError`` exception the first time +a setting is accessed. -If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then* -call ``configure()``, Django will raise a ``RuntimeError`` indicating +If you set :envvar:`DJANGO_SETTINGS_MODULE`, access settings values somehow, +*then* call ``configure()``, Django will raise a ``RuntimeError`` indicating that settings have already been configured. There is a property for this purpose: @@ -262,7 +262,7 @@ Also, it's an error to call ``configure()`` more than once, or to call ``configure()`` after any setting has been accessed. It boils down to this: Use exactly one of either ``configure()`` or -``DJANGO_SETTINGS_MODULE``. Not both, and not neither. +:envvar:`DJANGO_SETTINGS_MODULE`. Not both, and not neither. Calling ``django.setup()`` is required for "standalone" Django usage --------------------------------------------------------------------