diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 9d7e28b164..bef244b22e 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -699,12 +699,12 @@ complex conversions between your Python types and your database and serialization formats. Here are a couple of tips to make things go more smoothly: -1. Look at the existing Django fields (in +#. Look at the existing Django fields (in :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find a field that's similar to what you want and extend it a little bit, instead of creating an entirely new field from scratch. -2. Put a ``__str__()`` method on the class you're wrapping up as a field. There +#. Put a ``__str__()`` method on the class you're wrapping up as a field. There are a lot of places where the default behavior of the field code is to call ``str()`` on the value. (In our examples in this document, ``value`` would be a ``Hand`` instance, not a ``HandField``). So if your ``__str__()`` @@ -736,12 +736,12 @@ A few suggestions In addition to the above details, there are a few guidelines which can greatly improve the efficiency and readability of the field's code. -1. The source for Django's own ``ImageField`` (in +#. The source for Django's own ``ImageField`` (in ``django/db/models/fields/files.py``) is a great example of how to subclass ``FileField`` to support a particular type of file, as it incorporates all of the techniques described above. -2. Cache file attributes wherever possible. Since files may be stored in +#. Cache file attributes wherever possible. Since files may be stored in remote storage systems, retrieving them may cost extra time, or even money, that isn't always necessary. Once a file is retrieved to obtain some data about its content, cache as much of that data as possible to diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 851c35dc1c..aa61b912b4 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -842,13 +842,13 @@ A naive implementation of ``CycleNode`` might look something like this:: But, suppose we have two templates rendering the template snippet from above at the same time: -1. Thread 1 performs its first loop iteration, ``CycleNode.render()`` +#. Thread 1 performs its first loop iteration, ``CycleNode.render()`` returns 'row1' -2. Thread 2 performs its first loop iteration, ``CycleNode.render()`` +#. Thread 2 performs its first loop iteration, ``CycleNode.render()`` returns 'row2' -3. Thread 1 performs its second loop iteration, ``CycleNode.render()`` +#. Thread 1 performs its second loop iteration, ``CycleNode.render()`` returns 'row1' -4. Thread 2 performs its second loop iteration, ``CycleNode.render()`` +#. Thread 2 performs its second loop iteration, ``CycleNode.render()`` returns 'row2' The CycleNode is iterating, but it's iterating globally. As far as Thread 1 diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index b94a332549..c21c75a8d1 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -11,14 +11,14 @@ This page describes how you can serve these static files. Configuring static files ======================== -1. Make sure that ``django.contrib.staticfiles`` is included in your +#. Make sure that ``django.contrib.staticfiles`` is included in your :setting:`INSTALLED_APPS`. -2. In your settings file, define :setting:`STATIC_URL`, for example:: +#. In your settings file, define :setting:`STATIC_URL`, for example:: STATIC_URL = '/static/' -3. In your templates, use the :ttag:`static` template tag to build the URL for +#. In your templates, use the :ttag:`static` template tag to build the URL for the given relative path using the configured :setting:`STATICFILES_STORAGE`. .. _staticfiles-in-templates: @@ -28,7 +28,7 @@ Configuring static files {% load static %} My image -4. Store your static files in a folder called ``static`` in your app. For +#. Store your static files in a folder called ``static`` in your app. For example ``my_app/static/my_app/example.jpg``. .. admonition:: Serving the files @@ -159,19 +159,19 @@ Deployment :mod:`django.contrib.staticfiles` provides a convenience management command for gathering static files in a single directory so you can serve them easily. -1. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd +#. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd like to serve these files, for example:: STATIC_ROOT = "/var/www/example.com/static/" -2. Run the :djadmin:`collectstatic` management command:: +#. Run the :djadmin:`collectstatic` management command:: $ python manage.py collectstatic This will copy all files from your static folders into the :setting:`STATIC_ROOT` directory. -3. Use a web server of your choice to serve the +#. Use a web server of your choice to serve the files. :doc:`/howto/static-files/deployment` covers some common deployment strategies for static files. diff --git a/docs/internals/organization.txt b/docs/internals/organization.txt index 18e7147c49..b2d399255f 100644 --- a/docs/internals/organization.txt +++ b/docs/internals/organization.txt @@ -168,12 +168,12 @@ A new board is elected after each feature release of Django. The election process is managed by a returns officer nominated by the outgoing technical board. The election process works as follows: -1. Candidates advertise their application for the technical board to the team. +#. Candidates advertise their application for the technical board to the team. They must be committers already. There's no term limit for technical board members. -2. Each team member can vote for zero to five people among the candidates. +#. Each team member can vote for zero to five people among the candidates. Candidates are ranked by the total number of votes they received. In case of a tie, the person who joined the core team earlier wins. diff --git a/docs/internals/security.txt b/docs/internals/security.txt index 721a4881b7..8fb9583b63 100644 --- a/docs/internals/security.txt +++ b/docs/internals/security.txt @@ -119,18 +119,18 @@ from `Django's release team`_ and consists of: On the day of disclosure, we will take the following steps: -1. Apply the relevant patch(es) to Django's codebase. +#. Apply the relevant patch(es) to Django's codebase. -2. Issue the relevant release(s), by placing new packages on `the +#. Issue the relevant release(s), by placing new packages on `the Python Package Index`_ and on the Django website, and tagging the new release(s) in Django's git repository. -3. Post a public entry on `the official Django development blog`_, +#. Post a public entry on `the official Django development blog`_, describing the issue and its resolution in detail, pointing to the relevant patches and new releases, and crediting the reporter of the issue (if the reporter wishes to be publicly identified). -4. Post a notice to the |django-announce| and oss-security@lists.openwall.com +#. Post a notice to the |django-announce| and oss-security@lists.openwall.com mailing lists that links to the blog post. .. _the Python Package Index: https://pypi.org/ diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index e76bab8173..61c413de00 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -120,7 +120,7 @@ Python *packaging* refers to preparing your app in a specific format that can be easily installed and used. Django itself is packaged very much like this. For a small app like polls, this process isn't too difficult. -1. First, create a parent directory for ``polls``, outside of your Django +#. First, create a parent directory for ``polls``, outside of your Django project. Call this directory ``django-polls``. .. admonition:: Choosing a name for your app @@ -137,9 +137,9 @@ this. For a small app like polls, this process isn't too difficult. `, for example ``auth``, ``admin``, or ``messages``. -2. Move the ``polls`` directory into the ``django-polls`` directory. +#. Move the ``polls`` directory into the ``django-polls`` directory. -3. Create a file ``django-polls/README.rst`` with the following contents: +#. Create a file ``django-polls/README.rst`` with the following contents: .. code-block:: rst :caption: django-polls/README.rst @@ -174,14 +174,14 @@ this. For a small app like polls, this process isn't too difficult. 5. Visit http://127.0.0.1:8000/polls/ to participate in the poll. -4. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the +#. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the scope of this tutorial, but suffice it to say that code released publicly without a license is *useless*. Django and many Django-compatible apps are distributed under the BSD license; however, you're free to pick your own license. Just be aware that your licensing choice will affect who is able to use your code. -5. Next we'll create a ``setup.py`` file which provides details about how to +#. Next we'll create a ``setup.py`` file which provides details about how to build and install the app. A full explanation of this file is beyond the scope of this tutorial, but the `setuptools docs `_ have a good @@ -226,7 +226,7 @@ this. For a small app like polls, this process isn't too difficult. ], ) -6. Only Python modules and packages are included in the package by default. To +#. Only Python modules and packages are included in the package by default. To include additional files, we'll need to create a ``MANIFEST.in`` file. The setuptools docs referred to in the previous step discuss this file in more details. To include the templates, the ``README.rst`` and our ``LICENSE`` @@ -241,7 +241,7 @@ this. For a small app like polls, this process isn't too difficult. recursive-include polls/static * recursive-include polls/templates * -7. It's optional, but recommended, to include detailed documentation with your +#. It's optional, but recommended, to include detailed documentation with your app. Create an empty directory ``django-polls/docs`` for future documentation. Add an additional line to ``django-polls/MANIFEST.in``:: @@ -251,7 +251,7 @@ this. For a small app like polls, this process isn't too difficult. you add some files to it. Many Django apps also provide their documentation online through sites like `readthedocs.org `_. -8. Try building your package with ``python setup.py sdist`` (run from inside +#. Try building your package with ``python setup.py sdist`` (run from inside ``django-polls``). This creates a directory called ``dist`` and builds your new package, ``django-polls-0.1.tar.gz``. @@ -276,15 +276,15 @@ working. We'll now fix this by installing our new ``django-polls`` package. tools that run as that user, so ``virtualenv`` is a more robust solution (see below). -1. To install the package, use pip (you already :ref:`installed it +#. To install the package, use pip (you already :ref:`installed it `, right?):: pip install --user django-polls/dist/django-polls-0.1.tar.gz -2. With luck, your Django project should now work correctly again. Run the +#. With luck, your Django project should now work correctly again. Run the server again to confirm this. -3. To uninstall the package, use pip:: +#. To uninstall the package, use pip:: pip uninstall django-polls diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index 2eacd297ed..6bfe506d70 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -211,11 +211,11 @@ Let's convert our poll app to use the generic views system, so we can delete a bunch of our own code. We'll just have to take a few steps to make the conversion. We will: -1. Convert the URLconf. +#. Convert the URLconf. -2. Delete some of the old, unneeded views. +#. Delete some of the old, unneeded views. -3. Introduce new views based on Django's generic views. +#. Introduce new views based on Django's generic views. Read on for details. diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index 35d2118a27..0875b50808 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -303,10 +303,10 @@ Django applications require a single base filesystem path where Django etc. Thus, namespace packages may only be Django applications if one of the following is true: -1. The namespace package actually has only a single location (i.e. is not +#. The namespace package actually has only a single location (i.e. is not spread across more than one directory.) -2. The :class:`~django.apps.AppConfig` class used to configure the application +#. The :class:`~django.apps.AppConfig` class used to configure the application has a :attr:`~django.apps.AppConfig.path` class attribute, which is the absolute directory path Django will use as the single base path for the application. diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 6ef72176c3..3b753a1a3d 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -24,9 +24,9 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - 1. :meth:`dispatch()` - 2. :meth:`http_method_not_allowed()` - 3. :meth:`options()` + #. :meth:`dispatch()` + #. :meth:`http_method_not_allowed()` + #. :meth:`options()` **Example views.py**:: @@ -123,9 +123,9 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - 1. :meth:`~django.views.generic.base.View.dispatch()` - 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - 3. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` + #. :meth:`~django.views.generic.base.View.dispatch()` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + #. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` **Example views.py**:: @@ -184,9 +184,9 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - 1. :meth:`~django.views.generic.base.View.dispatch()` - 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - 3. :meth:`get_redirect_url()` + #. :meth:`~django.views.generic.base.View.dispatch()` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + #. :meth:`get_redirect_url()` **Example views.py**:: diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index 044f16d9e5..e7b2163818 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -25,16 +25,16 @@ many projects they are typically the most commonly used views. **Method Flowchart** - 1. :meth:`~django.views.generic.base.View.dispatch()` - 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - 3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` - 4. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()` - 5. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()` - 6. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` - 7. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()` - 8. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()` - 9. ``get()`` - 10. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` + #. :meth:`~django.views.generic.base.View.dispatch()` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()` + #. ``get()`` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` **Example myapp/views.py**:: @@ -95,15 +95,14 @@ many projects they are typically the most commonly used views. **Method Flowchart** - 1. :meth:`~django.views.generic.base.View.dispatch()` - 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - 3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` - 4. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()` - 5. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()` - 6. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()` - 7. ``get()`` - 8. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` - + #. :meth:`~django.views.generic.base.View.dispatch()` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()` + #. ``get()`` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` **Example views.py**:: diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index ade7069db5..6fba3eaea8 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -40,9 +40,9 @@ loading in a frame no matter which site made the request. Django provides a few simple ways to include this header in responses from your site: -1. A simple middleware that sets the header in all responses. +#. A simple middleware that sets the header in all responses. -2. A set of view decorators that can be used to override the middleware or to +#. A set of view decorators that can be used to override the middleware or to only set the header for certain views. The ``X-Frame-Options`` HTTP header will only be set by the middleware or view diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index 7dddf27660..3a05e19864 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -8,9 +8,9 @@ Overview ======== In general, GeoDjango installation requires: -1. :ref:`Python and Django ` -2. :ref:`spatial_database` -3. :doc:`geolibs` +#. :ref:`Python and Django ` +#. :ref:`spatial_database` +#. :doc:`geolibs` Details for each of the requirements and installation instructions are provided in the sections below. In addition, platform-specific diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index f273fa9c20..8aef4a1614 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -31,7 +31,7 @@ then inserting into a GeoDjango model. Example ======= -1. You need a GDAL-supported data source, like a shapefile (here we're using +#. You need a GDAL-supported data source, like a shapefile (here we're using a simple polygon shapefile, ``test_poly.shp``, with three features):: >>> from django.contrib.gis.gdal import DataSource @@ -50,7 +50,7 @@ Example PRIMEM["Greenwich",0], UNIT["Degree",0.017453292519943295]] -2. Now we define our corresponding Django model (make sure to use :djadmin:`migrate`):: +#. Now we define our corresponding Django model (make sure to use :djadmin:`migrate`):: from django.contrib.gis.db import models @@ -61,7 +61,7 @@ Example def __str__(self): return 'Name: %s' % self.name -3. Use :class:`LayerMapping` to extract all the features and place them in the +#. Use :class:`LayerMapping` to extract all the features and place them in the database:: >>> from django.contrib.gis.utils import LayerMapping diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index c82fb0adaf..01d47af55b 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -292,8 +292,8 @@ transform do not change. For example:: To use this field, you'll need to: - 1. Add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`. - 2. :ref:`Setup the hstore extension ` in + #. Add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`. + #. :ref:`Setup the hstore extension ` in PostgreSQL. You'll see an error like ``can't adapt type 'dict'`` if you skip the first diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 8af48ba8b2..15417d6f30 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -14,12 +14,12 @@ Installation To install the redirects app, follow these steps: -1. Ensure that the ``django.contrib.sites`` framework +#. Ensure that the ``django.contrib.sites`` framework :ref:`is installed `. -2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting. -3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` +#. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting. +#. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` to your :setting:`MIDDLEWARE` setting. -4. Run the command :djadmin:`manage.py migrate `. +#. Run the command :djadmin:`manage.py migrate `. How it works ============ diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 21ed6848e4..67ba9e60bb 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -31,15 +31,13 @@ Installation To install the sitemap app, follow these steps: -1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` - setting. +#. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` setting. -2. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates`` +#. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates`` backend whose ``APP_DIRS`` options is set to ``True``. It's in there by default, so you'll only need to change this if you've changed that setting. -3. Make sure you've installed the - :mod:`sites framework `. +#. Make sure you've installed the :mod:`sites framework`. (Note: The sitemap application doesn't install any database tables. The only reason it needs to go into :setting:`INSTALLED_APPS` is so that the diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index b5c3889bef..0a808f23a9 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -261,14 +261,13 @@ Enabling the sites framework To enable the sites framework, follow these steps: -1. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` - setting. +#. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting. -2. Define a :setting:`SITE_ID` setting:: +#. Define a :setting:`SITE_ID` setting:: SITE_ID = 1 -3. Run :djadmin:`migrate`. +#. Run :djadmin:`migrate`. ``django.contrib.sites`` registers a :data:`~django.db.models.signals.post_migrate` signal handler which creates a diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt index bb12e07c93..19ddc1345a 100644 --- a/docs/ref/csrf.txt +++ b/docs/ref/csrf.txt @@ -27,7 +27,7 @@ How to use it To take advantage of CSRF protection in your views, follow these steps: -1. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE` +#. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE` setting. If you override that setting, remember that ``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any view middleware that assume that CSRF attacks have been dealt with. @@ -36,7 +36,7 @@ To take advantage of CSRF protection in your views, follow these steps: :func:`~django.views.decorators.csrf.csrf_protect` on particular views you want to protect (see below). -2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside +#. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside the ``
`` element if the form is for an internal URL, e.g.: .. code-block:: html+django @@ -46,7 +46,7 @@ To take advantage of CSRF protection in your views, follow these steps: This should not be done for POST forms that target external URLs, since that would cause the CSRF token to be leaked, leading to a vulnerability. -3. In the corresponding view functions, ensure that +#. In the corresponding view functions, ensure that :class:`~django.template.RequestContext` is used to render the response so that ``{% csrf_token %}`` will work properly. If you're using the :func:`~django.shortcuts.render` function, generic views, or contrib apps, @@ -241,7 +241,7 @@ How it works The CSRF protection is based on the following things: -1. A CSRF cookie that is based on a random secret value, which other sites +#. A CSRF cookie that is based on a random secret value, which other sites will not have access to. This cookie is set by ``CsrfViewMiddleware``. It is sent with every @@ -255,7 +255,7 @@ The CSRF protection is based on the following things: For security reasons, the value of the secret is changed each time a user logs in. -2. A hidden form field with the name 'csrfmiddlewaretoken' present in all +#. A hidden form field with the name 'csrfmiddlewaretoken' present in all outgoing POST forms. The value of this field is, again, the value of the secret, with a salt which is both added to it and used to scramble it. The salt is regenerated on every call to ``get_token()`` so that the form field @@ -263,7 +263,7 @@ The CSRF protection is based on the following things: This part is done by the template tag. -3. For all incoming requests that are not using HTTP GET, HEAD, OPTIONS or +#. For all incoming requests that are not using HTTP GET, HEAD, OPTIONS or TRACE, a CSRF cookie must be present, and the 'csrfmiddlewaretoken' field must be present and correct. If it isn't, the user will get a 403 error. @@ -274,7 +274,7 @@ The CSRF protection is based on the following things: This check is done by ``CsrfViewMiddleware``. -4. In addition, for HTTPS requests, strict referer checking is done by +#. In addition, for HTTPS requests, strict referer checking is done by ``CsrfViewMiddleware``. This means that even if a subdomain can set or modify cookies on your domain, it can't force a user to post to your application since that request won't come from your own exact domain. diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 16dd625267..39b3fb9898 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -415,10 +415,10 @@ Refer to the :doc:`settings documentation `. Connection settings are used in this order: -1. :setting:`OPTIONS`. -2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, - :setting:`HOST`, :setting:`PORT` -3. MySQL option files. +#. :setting:`OPTIONS`. +#. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, :setting:`HOST`, + :setting:`PORT` +#. MySQL option files. In other words, if you set the name of the database in :setting:`OPTIONS`, this will take precedence over :setting:`NAME`, which would override diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index f7fa7777e6..c1844b8e64 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1400,10 +1400,10 @@ For example, this command:: ...would perform the following steps: -1. Create a test database, as described in :ref:`the-test-database`. -2. Populate the test database with fixture data from the given fixtures. +#. Create a test database, as described in :ref:`the-test-database`. +#. Populate the test database with fixture data from the given fixtures. (For more on fixtures, see the documentation for :djadmin:`loaddata` above.) -3. Runs the Django development server (as in :djadmin:`runserver`), pointed at +#. Runs the Django development server (as in :djadmin:`runserver`), pointed at this newly created test database instead of your production database. This is useful in a number of ways: diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index bb2f7fff59..2d95233351 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -697,17 +697,17 @@ The default form widget for this field is a Using a :class:`FileField` or an :class:`ImageField` (see below) in a model takes a few steps: -1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the +#. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the full path to a directory where you'd like Django to store uploaded files. (For performance, these files are not stored in the database.) Define :setting:`MEDIA_URL` as the base public URL of that directory. Make sure that this directory is writable by the Web server's user account. -2. Add the :class:`FileField` or :class:`ImageField` to your model, defining +#. Add the :class:`FileField` or :class:`ImageField` to your model, defining the :attr:`~FileField.upload_to` option to specify a subdirectory of :setting:`MEDIA_ROOT` to use for uploaded files. -3. All that will be stored in your database is a path to the file +#. All that will be stored in your database is a path to the file (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the convenience :attr:`~django.db.models.fields.files.FieldFile.url` attribute provided by Django. For example, if your :class:`ImageField` is called diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 35be4e5107..0559b32765 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -32,7 +32,7 @@ that, you need to :meth:`~Model.save()`. signature as any change may prevent the model instance from being saved. Rather than overriding ``__init__``, try using one of these approaches: - 1. Add a classmethod on the model class:: + #. Add a classmethod on the model class:: from django.db import models @@ -47,7 +47,7 @@ that, you need to :meth:`~Model.save()`. book = Book.create("Pride and Prejudice") - 2. Add a method on a custom manager (usually preferred):: + #. Add a method on a custom manager (usually preferred):: class BookManager(models.Manager): def create_book(self, title): @@ -135,9 +135,9 @@ If you need to reload a model's values from the database, you can use the ``refresh_from_db()`` method. When this method is called without arguments the following is done: -1. All non-deferred fields of the model are updated to the values currently +#. All non-deferred fields of the model are updated to the values currently present in the database. -2. Any cached relations are cleared from the reloaded instance. +#. Any cached relations are cleared from the reloaded instance. Only fields of the model are reloaded from the database. Other database-dependent values such as annotations aren't reloaded. Any diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 4aedd4b92a..cbc199ba3d 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -163,12 +163,12 @@ Django quotes column and table names behind the scenes. the *only* difference when ``managed=False``. All other aspects of model handling are exactly the same as normal. This includes - 1. Adding an automatic primary key field to the model if you don't + #. Adding an automatic primary key field to the model if you don't declare it. To avoid confusion for later code readers, it's recommended to specify all the columns from the database table you are modeling when using unmanaged models. - 2. If a model with ``managed=False`` contains a + #. If a model with ``managed=False`` contains a :class:`~django.db.models.ManyToManyField` that points to another unmanaged model, then the intermediate table for the many-to-many join will also not be created. However, the intermediary table diff --git a/docs/topics/auth/index.txt b/docs/topics/auth/index.txt index 3224af74c7..3a3253a5ac 100644 --- a/docs/topics/auth/index.txt +++ b/docs/topics/auth/index.txt @@ -62,9 +62,9 @@ startproject `, these consist of two items listed in your and these items in your :setting:`MIDDLEWARE` setting: -1. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages +#. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages :doc:`sessions ` across requests. -2. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates +#. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates users with requests using sessions. With these settings in place, running the command ``manage.py migrate`` creates diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index fa2fddaa16..4a4497cf8a 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -86,11 +86,11 @@ use of Argon2 rather than the other algorithms supported by Django. To use Argon2 as your default storage algorithm, do the following: -1. Install the `argon2-cffi library`_. This can be done by running ``pip +#. Install the `argon2-cffi library`_. This can be done by running ``pip install django[argon2]``, which is equivalent to ``pip install argon2-cffi`` (along with any version requirement from Django's ``setup.py``). -2. Modify :setting:`PASSWORD_HASHERS` to list ``Argon2PasswordHasher`` first. +#. Modify :setting:`PASSWORD_HASHERS` to list ``Argon2PasswordHasher`` first. That is, in your settings file, you'd put:: PASSWORD_HASHERS = [ @@ -115,11 +115,11 @@ use it Django supports bcrypt with minimal effort. To use Bcrypt as your default storage algorithm, do the following: -1. Install the `bcrypt library`_. This can be done by running ``pip install +#. Install the `bcrypt library`_. This can be done by running ``pip install django[bcrypt]``, which is equivalent to ``pip install bcrypt`` (along with any version requirement from Django's ``setup.py``). -2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptSHA256PasswordHasher`` +#. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptSHA256PasswordHasher`` first. That is, in your settings file, you'd put:: PASSWORD_HASHERS = [ @@ -153,7 +153,7 @@ you'll subclass the appropriate algorithm and override the ``iterations`` parameters. For example, to increase the number of iterations used by the default PBKDF2 algorithm: -1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``:: +#. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``:: from django.contrib.auth.hashers import PBKDF2PasswordHasher @@ -166,7 +166,7 @@ default PBKDF2 algorithm: Save this somewhere in your project. For example, you might put this in a file like ``myproject/hashers.py``. -2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`:: +#. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`:: PASSWORD_HASHERS = [ 'myproject.hashers.MyPBKDF2PasswordHasher', diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt index 617f3febbf..f5bd88acaf 100644 --- a/docs/topics/conditional-view-processing.txt +++ b/docs/topics/conditional-view-processing.txt @@ -176,16 +176,16 @@ trying to change has been altered in the meantime. For example, consider the following exchange between the client and server: -1. Client requests ``/foo/``. -2. Server responds with some content with an ETag of ``"abcd1234"``. -3. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the +#. Client requests ``/foo/``. +#. Server responds with some content with an ETag of ``"abcd1234"``. +#. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the resource. It also sends an ``If-Match: "abcd1234"`` header to specify the version it is trying to update. -4. Server checks to see if the resource has changed, by computing the ETag +#. Server checks to see if the resource has changed, by computing the ETag the same way it does for a ``GET`` request (using the same function). If the resource *has* changed, it will return a 412 status code, meaning "precondition failed". -5. Client sends a ``GET`` request to ``/foo/``, after receiving a 412 +#. Client sends a ``GET`` request to ``/foo/``, after receiving a 412 response, to retrieve an updated version of the content before updating it. diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 441d7c8079..1a340a4567 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -651,19 +651,19 @@ Field name restrictions Django places some restrictions on model field names: -1. A field name cannot be a Python reserved word, because that would result +#. A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:: class Example(models.Model): pass = models.IntegerField() # 'pass' is a reserved word! -2. A field name cannot contain more than one underscore in a row, due to +#. A field name cannot contain more than one underscore in a row, due to the way Django's query lookup syntax works. For example:: class Example(models.Model): foo__bar = models.IntegerField() # 'foo__bar' has two underscores! -3. A field name cannot end with an underscore, for similar reasons. +#. A field name cannot end with an underscore, for similar reasons. These limitations can be worked around, though, because your field name doesn't necessarily have to match your database column name. See the @@ -1307,11 +1307,11 @@ directly inherit its fields and managers. The general rules are: -1. If you are mirroring an existing model or database table and don't want +#. If you are mirroring an existing model or database table and don't want all the original database table columns, use ``Meta.managed=False``. That option is normally useful for modeling database views and tables not under the control of Django. -2. If you are wanting to change the Python-only behavior of a model, but +#. If you are wanting to change the Python-only behavior of a model, but keep all the same fields as in the original, use ``Meta.proxy=True``. This sets things up so that the proxy model is an exact copy of the storage structure of the original model when data is saved. diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index dad68f58af..6c2946645e 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -283,7 +283,7 @@ many-to-many relation to User, the following template code is optimal: It is optimal because: -1. Since QuerySets are lazy, this does no database queries if 'display_inbox' +#. Since QuerySets are lazy, this does no database queries if 'display_inbox' is False. #. Use of :ttag:`with` means that we store ``user.emails.all`` in a variable diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 8340c0f096..6cf1570ab0 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -148,9 +148,9 @@ Instantiating, processing, and rendering forms When rendering an object in Django, we generally: -1. get hold of it in the view (fetch it from the database, for example) -2. pass it to the template context -3. expand it to HTML markup using template variables +#. get hold of it in the view (fetch it from the database, for example) +#. pass it to the template context +#. expand it to HTML markup using template variables Rendering a form in a template involves nearly the same work as rendering any other kind of object, but there are some key differences. diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index 86283af7fa..3b96eae4e8 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -319,7 +319,7 @@ may need some changes to adjust to the new semantics. These are the behavioral differences between using :setting:`MIDDLEWARE` and ``MIDDLEWARE_CLASSES``: -1. Under ``MIDDLEWARE_CLASSES``, every middleware will always have its +#. Under ``MIDDLEWARE_CLASSES``, every middleware will always have its ``process_response`` method called, even if an earlier middleware short-circuited by returning a response from its ``process_request`` method. Under :setting:`MIDDLEWARE`, middleware behaves more like an onion: @@ -328,7 +328,7 @@ These are the behavioral differences between using :setting:`MIDDLEWARE` and that middleware and the ones before it in :setting:`MIDDLEWARE` will see the response. -2. Under ``MIDDLEWARE_CLASSES``, ``process_exception`` is applied to +#. Under ``MIDDLEWARE_CLASSES``, ``process_exception`` is applied to exceptions raised from a middleware ``process_request`` method. Under :setting:`MIDDLEWARE`, ``process_exception`` applies only to exceptions raised from the view (or from the ``render`` method of a @@ -336,7 +336,7 @@ These are the behavioral differences between using :setting:`MIDDLEWARE` and a middleware are converted to the appropriate HTTP response and then passed to the next middleware. -3. Under ``MIDDLEWARE_CLASSES``, if a ``process_response`` method raises +#. Under ``MIDDLEWARE_CLASSES``, if a ``process_response`` method raises an exception, the ``process_response`` methods of all earlier middleware are skipped and a ``500 Internal Server Error`` HTTP response is always returned (even if the exception raised was e.g. an diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 7b3a3a2c00..1aca4ce287 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -119,7 +119,7 @@ Examples You can use the :func:`redirect` function in a number of ways. -1. By passing some object; that object's +#. By passing some object; that object's :meth:`~django.db.models.Model.get_absolute_url` method will be called to figure out the redirect URL:: @@ -130,7 +130,7 @@ You can use the :func:`redirect` function in a number of ways. obj = MyModel.objects.get(...) return redirect(obj) -2. By passing the name of a view and optionally some positional or +#. By passing the name of a view and optionally some positional or keyword arguments; the URL will be reverse resolved using the :func:`~django.urls.reverse` method:: @@ -138,7 +138,7 @@ You can use the :func:`redirect` function in a number of ways. ... return redirect('some-view-name', foo='bar') -3. By passing a hardcoded URL to redirect to:: +#. By passing a hardcoded URL to redirect to:: def my_view(request): ... diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index c43f2181dd..d1b84e851c 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -34,20 +34,20 @@ How Django processes a request When a user requests a page from your Django-powered site, this is the algorithm the system follows to determine which Python code to execute: -1. Django determines the root URLconf module to use. Ordinarily, +#. Django determines the root URLconf module to use. Ordinarily, this is the value of the :setting:`ROOT_URLCONF` setting, but if the incoming ``HttpRequest`` object has a :attr:`~django.http.HttpRequest.urlconf` attribute (set by middleware), its value will be used in place of the :setting:`ROOT_URLCONF` setting. -2. Django loads that Python module and looks for the variable +#. Django loads that Python module and looks for the variable ``urlpatterns``. This should be a Python list of :func:`django.urls.path` and/or :func:`django.urls.re_path` instances. -3. Django runs through each URL pattern, in order, and stops at the first +#. Django runs through each URL pattern, in order, and stops at the first one that matches the requested URL. -4. Once one of the URL patterns matches, Django imports and calls the given +#. Once one of the URL patterns matches, Django imports and calls the given view, which is a simple Python function (or a :doc:`class-based view `). The view gets passed the following arguments: @@ -60,7 +60,7 @@ algorithm the system follows to determine which Python code to execute: ``kwargs`` argument to :func:`django.urls.path` or :func:`django.urls.re_path`. -5. If no URL pattern matches, or if an exception is raised during any +#. If no URL pattern matches, or if an exception is raised during any point in this process, Django invokes an appropriate error-handling view. See `Error handling`_ below. @@ -718,11 +718,11 @@ Reversing namespaced URLs When given a namespaced URL (e.g. ``'polls:index'``) to resolve, Django splits the fully qualified name into parts and then tries the following lookup: -1. First, Django looks for a matching :term:`application namespace` (in this +#. First, Django looks for a matching :term:`application namespace` (in this example, ``'polls'``). This will yield a list of instances of that application. -2. If there is a current application defined, Django finds and returns the URL +#. If there is a current application defined, Django finds and returns the URL resolver for that instance. The current application can be specified with the ``current_app`` argument to the :func:`~django.urls.reverse()` function. @@ -733,15 +733,15 @@ the fully qualified name into parts and then tries the following lookup: setting the current application on the :attr:`request.current_app ` attribute. -3. If there is no current application, Django looks for a default +#. If there is no current application, Django looks for a default application instance. The default application instance is the instance that has an :term:`instance namespace` matching the :term:`application namespace` (in this example, an instance of ``polls`` called ``'polls'``). -4. If there is no default application instance, Django will pick the last +#. If there is no default application instance, Django will pick the last deployed instance of the application, whatever its instance name may be. -5. If the provided namespace doesn't match an :term:`application namespace` in +#. If the provided namespace doesn't match an :term:`application namespace` in step 1, Django will attempt a direct lookup of the namespace as an :term:`instance namespace`. diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt index eb97677777..86fd8b5062 100644 --- a/docs/topics/i18n/timezones.txt +++ b/docs/topics/i18n/timezones.txt @@ -462,7 +462,7 @@ FAQ Setup ----- -1. **I don't need multiple time zones. Should I enable time zone support?** +#. **I don't need multiple time zones. Should I enable time zone support?** Yes. When time zone support is enabled, Django uses a more accurate model of local time. This shields you from subtle and unreproducible bugs around @@ -481,7 +481,7 @@ Setup For these reasons, time zone support is enabled by default in new projects, and you should keep it unless you have a very good reason not to. -2. **I've enabled time zone support. Am I safe?** +#. **I've enabled time zone support. Am I safe?** Maybe. You're better protected from DST-related bugs, but you can still shoot yourself in the foot by carelessly turning naive datetimes into aware @@ -508,7 +508,7 @@ Setup one year is 2011-02-28 or 2011-03-01, which depends on your business requirements.) -3. **How do I interact with a database that stores datetimes in local time?** +#. **How do I interact with a database that stores datetimes in local time?** Set the :setting:`TIME_ZONE ` option to the appropriate time zone for this database in the :setting:`DATABASES` setting. @@ -519,7 +519,7 @@ Setup Troubleshooting --------------- -1. **My application crashes with** ``TypeError: can't compare offset-naive`` +#. **My application crashes with** ``TypeError: can't compare offset-naive`` ``and offset-aware datetimes`` **-- what's wrong?** Let's reproduce this error by comparing a naive and an aware datetime:: @@ -551,7 +551,7 @@ Troubleshooting datetime when ``USE_TZ = True``. You can add or subtract :class:`datetime.timedelta` as needed. -2. **I see lots of** ``RuntimeWarning: DateTimeField received a naive +#. **I see lots of** ``RuntimeWarning: DateTimeField received a naive datetime`` ``(YYYY-MM-DD HH:MM:SS)`` ``while time zone support is active`` **-- is that bad?** @@ -564,7 +564,7 @@ Troubleshooting In the meantime, for backwards compatibility, the datetime is considered to be in the default time zone, which is generally what you expect. -3. ``now.date()`` **is yesterday! (or tomorrow)** +#. ``now.date()`` **is yesterday! (or tomorrow)** If you've always used naive datetimes, you probably believe that you can convert a datetime to a date by calling its :meth:`~datetime.datetime.date` @@ -623,7 +623,7 @@ Troubleshooting >>> local.date() datetime.date(2012, 3, 3) -4. **I get an error** "``Are time zone definitions for your database +#. **I get an error** "``Are time zone definitions for your database installed?``" If you are using MySQL, see the :ref:`mysql-time-zone-definitions` section @@ -632,7 +632,7 @@ Troubleshooting Usage ----- -1. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the** +#. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the** ``"Europe/Helsinki"`` **time zone. How do I turn that into an aware datetime?** @@ -649,7 +649,7 @@ Usage documentation of pytz contains `more examples`_. You should review it before attempting to manipulate aware datetimes. -2. **How can I obtain the local time in the current time zone?** +#. **How can I obtain the local time in the current time zone?** Well, the first question is, do you really need to? @@ -672,7 +672,7 @@ Usage In this example, the current time zone is ``"Europe/Paris"``. -3. **How can I see all available time zones?** +#. **How can I see all available time zones?** pytz_ provides helpers_, including a list of current time zones and a list of all available time zones -- some of which are only of historical diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 3adb3d91b9..3f2fcdd7e6 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -63,12 +63,12 @@ as a shorter alias, ``_``, to save typing. global namespace, as an alias for ``gettext()``. In Django, we have chosen not to follow this practice, for a couple of reasons: - 1. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy` + #. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy` as the default translation method for a particular file. Without ``_()`` in the global namespace, the developer has to think about which is the most appropriate translation function. - 2. The underscore character (``_``) is used to represent "the previous + #. The underscore character (``_``) is used to represent "the previous result" in Python's interactive shell and doctest tests. Installing a global ``_()`` function causes interference. Explicitly importing ``gettext()`` as ``_()`` avoids this problem. @@ -2073,13 +2073,13 @@ the order in which it examines the different file paths to load the compiled :term:`message files ` (``.mo``) and the precedence of multiple translations for the same literal: -1. The directories listed in :setting:`LOCALE_PATHS` have the highest +#. The directories listed in :setting:`LOCALE_PATHS` have the highest precedence, with the ones appearing first having higher precedence than the ones appearing later. -2. Then, it looks for and uses if it exists a ``locale`` directory in each +#. Then, it looks for and uses if it exists a ``locale`` directory in each of the installed apps listed in :setting:`INSTALLED_APPS`. The ones appearing first have higher precedence than the ones appearing later. -3. Finally, the Django-provided base translation in ``django/conf/locale`` +#. Finally, the Django-provided base translation in ``django/conf/locale`` is used as a fallback. .. seealso:: diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 3586160366..876a6b870b 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -140,18 +140,18 @@ Installing an official release with ``pip`` This is the recommended way to install Django. -1. Install pip_. The easiest is to use the `standalone pip installer`_. If your +#. Install pip_. The easiest is to use the `standalone pip installer`_. If your distribution already has ``pip`` installed, you might need to update it if it's outdated. If it's outdated, you'll know because installation won't work. -2. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide +#. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide isolated Python environments, which are more practical than installing packages systemwide. They also allow installing packages without administrator privileges. The :doc:`contributing tutorial ` walks through how to create a virtualenv. -3. After you've created and activated a virtual environment, enter the command +#. After you've created and activated a virtual environment, enter the command ``pip install Django`` at the shell prompt. .. _pip: https://pip.pypa.io/ @@ -191,10 +191,10 @@ Installing the development version If you'd like to be able to update your Django code occasionally with the latest bug fixes and improvements, follow these instructions: -1. Make sure that you have Git_ installed and that you can run its commands +#. Make sure that you have Git_ installed and that you can run its commands from a shell. (Enter ``git help`` at a shell prompt to test this.) -2. Check out Django's main development branch like so: +#. Check out Django's main development branch like so: .. console:: @@ -202,12 +202,12 @@ latest bug fixes and improvements, follow these instructions: This will create a directory ``django`` in your current directory. -3. Make sure that the Python interpreter can load Django's code. The most +#. Make sure that the Python interpreter can load Django's code. The most convenient way to do this is to use virtualenv_, virtualenvwrapper_, and pip_. The :doc:`contributing tutorial ` walks through how to create a virtualenv. -4. After setting up and activating the virtualenv, run the following command: +#. After setting up and activating the virtualenv, run the following command: .. console:: diff --git a/docs/topics/security.txt b/docs/topics/security.txt index 0eebdeb934..30d19190df 100644 --- a/docs/topics/security.txt +++ b/docs/topics/security.txt @@ -244,7 +244,7 @@ User-uploaded content validate all user uploaded file content, however, there are some other steps you can take to mitigate these attacks: - 1. One class of attacks can be prevented by always serving user uploaded + #. One class of attacks can be prevented by always serving user uploaded content from a distinct top-level or second-level domain. This prevents any exploit blocked by `same-origin policy`_ protections such as cross site scripting. For example, if your site runs on ``example.com``, you @@ -252,7 +252,7 @@ User-uploaded content from something like ``usercontent-example.com``. It's *not* sufficient to serve content from a subdomain like ``usercontent.example.com``. - 2. Beyond this, applications may choose to define a whitelist of allowable + #. Beyond this, applications may choose to define a whitelist of allowable file extensions for user uploaded files and configure the web server to only serve such files.