From 56955636e66505b7ac0246f97883f979d1b1f6a1 Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Fri, 27 Jun 2025 14:33:40 +0100 Subject: [PATCH] Ensured :doc: role uses absolute targets in docs. --- docs/contents.txt | 2 +- docs/howto/deployment/index.txt | 4 +- docs/index.txt | 302 +++++++++--------- .../contributing/committing-code.txt | 4 +- .../contributing/new-contributors.txt | 3 +- .../contributing/triaging-tickets.txt | 2 +- .../writing-code/coding-style.txt | 2 +- .../writing-code/submitting-patches.txt | 20 +- .../writing-code/working-with-git.txt | 2 +- docs/internals/release-process.txt | 3 +- docs/ref/contrib/admin/index.txt | 4 +- docs/ref/contrib/gis/db-api.txt | 14 +- docs/ref/contrib/gis/functions.txt | 3 +- docs/ref/contrib/gis/tutorial.txt | 36 ++- docs/ref/forms/api.txt | 10 +- docs/ref/logging.txt | 19 +- docs/ref/models/conditional-expressions.txt | 6 +- docs/ref/models/database-functions.txt | 4 +- docs/ref/models/expressions.txt | 5 +- docs/releases/1.11.txt | 3 +- docs/releases/1.3.txt | 2 +- docs/topics/auth/index.txt | 6 +- docs/topics/class-based-views/mixins.txt | 24 +- docs/topics/testing/index.txt | 4 +- 24 files changed, 247 insertions(+), 237 deletions(-) diff --git a/docs/contents.txt b/docs/contents.txt index 137b308921..5017bb8457 100644 --- a/docs/contents.txt +++ b/docs/contents.txt @@ -25,4 +25,4 @@ Indices, glossary and tables * :ref:`genindex` * :ref:`modindex` -* :doc:`glossary` +* :doc:`/glossary` diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index 2f53a97bef..5477aca805 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -29,8 +29,8 @@ You should also consider how you will handle :doc:`static files :doc:`error reporting`. Finally, before you deploy your application to production, you should run -through our :doc:`deployment checklist` to ensure that your -configurations are suitable. +through our :doc:`deployment checklist ` to ensure +that your configurations are suitable. .. _WSGI: https://wsgi.readthedocs.io/en/latest/ .. _ASGI: https://asgi.readthedocs.io/en/latest/ diff --git a/docs/index.txt b/docs/index.txt index 330e191e1c..b25a345a96 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -12,34 +12,34 @@ First steps Are you new to Django or to programming? This is the place to start! * **From scratch:** - :doc:`Overview ` | - :doc:`Installation ` + :doc:`Overview ` | + :doc:`Installation ` * **Tutorial:** - :doc:`Part 1: Requests and responses ` | - :doc:`Part 2: Models and the admin site ` | - :doc:`Part 3: Views and templates ` | - :doc:`Part 4: Forms and generic views ` | - :doc:`Part 5: Testing ` | - :doc:`Part 6: Static files ` | - :doc:`Part 7: Customizing the admin site ` | - :doc:`Part 8: Adding third-party packages ` + :doc:`Part 1: Requests and responses ` | + :doc:`Part 2: Models and the admin site ` | + :doc:`Part 3: Views and templates ` | + :doc:`Part 4: Forms and generic views ` | + :doc:`Part 5: Testing ` | + :doc:`Part 6: Static files ` | + :doc:`Part 7: Customizing the admin site ` | + :doc:`Part 8: Adding third-party packages ` * **Advanced Tutorials:** - :doc:`How to write reusable apps ` | - :doc:`Writing your first contribution to Django ` + :doc:`How to write reusable apps ` | + :doc:`Writing your first contribution to Django ` Getting help ============ Having trouble? We'd like to help! -* Try the :doc:`FAQ ` -- it's got answers to many common questions. +* Try the :doc:`FAQ ` -- it's got answers to many common questions. * Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or - the :doc:`detailed table of contents `. + the :doc:`detailed table of contents `. -* Not found anything? See :doc:`faq/help` for information on getting support +* Not found anything? See :doc:`/faq/help` for information on getting support and asking questions to the community. * Report bugs with Django in our `ticket tracker`_. @@ -74,46 +74,46 @@ Django provides an abstraction layer (the "models") for structuring and manipulating the data of your web application. Learn more about it below: * **Models:** - :doc:`Introduction to models ` | - :doc:`Field types ` | - :doc:`Indexes ` | - :doc:`Meta options ` | - :doc:`Model class ` + :doc:`Introduction to models ` | + :doc:`Field types ` | + :doc:`Indexes ` | + :doc:`Meta options ` | + :doc:`Model class ` * **QuerySets:** - :doc:`Making queries ` | - :doc:`QuerySet method reference ` | - :doc:`Lookup expressions ` + :doc:`Making queries ` | + :doc:`QuerySet method reference ` | + :doc:`Lookup expressions ` * **Model instances:** - :doc:`Instance methods ` | - :doc:`Accessing related objects ` + :doc:`Instance methods ` | + :doc:`Accessing related objects ` * **Migrations:** - :doc:`Introduction to Migrations` | - :doc:`Operations reference ` | - :doc:`SchemaEditor ` | - :doc:`Writing migrations ` + :doc:`Introduction to Migrations` | + :doc:`Operations reference ` | + :doc:`SchemaEditor ` | + :doc:`Writing migrations ` * **Advanced:** - :doc:`Managers ` | - :doc:`Raw SQL ` | - :doc:`Transactions ` | - :doc:`Aggregation ` | - :doc:`Search ` | - :doc:`Custom fields ` | - :doc:`Multiple databases ` | - :doc:`Custom lookups ` | - :doc:`Query Expressions ` | - :doc:`Conditional Expressions ` | - :doc:`Database Functions ` + :doc:`Managers ` | + :doc:`Raw SQL ` | + :doc:`Transactions ` | + :doc:`Aggregation ` | + :doc:`Search ` | + :doc:`Custom fields ` | + :doc:`Multiple databases ` | + :doc:`Custom lookups ` | + :doc:`Query Expressions ` | + :doc:`Conditional Expressions ` | + :doc:`Database Functions ` * **Other:** - :doc:`Supported databases ` | - :doc:`Legacy databases ` | - :doc:`Providing initial data ` | - :doc:`Optimize database access ` | - :doc:`PostgreSQL specific features ` + :doc:`Supported databases ` | + :doc:`Legacy databases ` | + :doc:`Providing initial data ` | + :doc:`Optimize database access ` | + :doc:`PostgreSQL specific features ` The view layer ============== @@ -123,39 +123,39 @@ processing a user's request and for returning the response. Find all you need to know about views via the links below: * **The basics:** - :doc:`URLconfs ` | - :doc:`View functions ` | - :doc:`Shortcuts ` | - :doc:`Decorators ` | - :doc:`Asynchronous Support ` + :doc:`URLconfs ` | + :doc:`View functions ` | + :doc:`Shortcuts ` | + :doc:`Decorators ` | + :doc:`Asynchronous Support ` * **Reference:** - :doc:`Built-in Views ` | - :doc:`Request/response objects ` | - :doc:`TemplateResponse objects ` + :doc:`Built-in Views ` | + :doc:`Request/response objects ` | + :doc:`TemplateResponse objects ` * **File uploads:** - :doc:`Overview ` | - :doc:`File objects ` | - :doc:`Storage API ` | - :doc:`Managing files ` | - :doc:`Custom storage ` + :doc:`Overview ` | + :doc:`File objects ` | + :doc:`Storage API ` | + :doc:`Managing files ` | + :doc:`Custom storage ` * **Class-based views:** - :doc:`Overview ` | - :doc:`Built-in display views ` | - :doc:`Built-in editing views ` | - :doc:`Using mixins ` | - :doc:`API reference ` | - :doc:`Flattened index` + :doc:`Overview ` | + :doc:`Built-in display views ` | + :doc:`Built-in editing views ` | + :doc:`Using mixins ` | + :doc:`API reference ` | + :doc:`Flattened index ` * **Advanced:** - :doc:`Generating CSV ` | - :doc:`Generating PDF ` + :doc:`Generating CSV ` | + :doc:`Generating PDF ` * **Middleware:** - :doc:`Overview ` | - :doc:`Built-in middleware classes ` + :doc:`Overview ` | + :doc:`Built-in middleware classes ` The template layer ================== @@ -165,17 +165,17 @@ information to be presented to the user. Learn how this syntax can be used by designers and how it can be extended by programmers: * **The basics:** - :doc:`Overview ` + :doc:`Overview ` * **For designers:** - :doc:`Language overview ` | - :doc:`Built-in tags and filters ` | - :doc:`Humanization ` + :doc:`Language overview ` | + :doc:`Built-in tags and filters ` | + :doc:`Humanization ` * **For programmers:** - :doc:`Template API ` | - :doc:`Custom tags and filters ` | - :doc:`Custom template backend ` + :doc:`Template API ` | + :doc:`Custom tags and filters ` | + :doc:`Custom template backend ` Forms ===== @@ -184,16 +184,16 @@ Django provides a rich framework to facilitate the creation of forms and the manipulation of form data. * **The basics:** - :doc:`Overview ` | - :doc:`Form API ` | - :doc:`Built-in fields ` | - :doc:`Built-in widgets ` + :doc:`Overview ` | + :doc:`Form API ` | + :doc:`Built-in fields ` | + :doc:`Built-in widgets ` * **Advanced:** - :doc:`Forms for models ` | - :doc:`Integrating media ` | - :doc:`Formsets ` | - :doc:`Customizing validation ` + :doc:`Forms for models ` | + :doc:`Integrating media ` | + :doc:`Formsets ` | + :doc:`Customizing validation ` The development process ======================= @@ -202,32 +202,32 @@ Learn about the various components and tools to help you in the development and testing of Django applications: * **Settings:** - :doc:`Overview ` | - :doc:`Full list of settings ` + :doc:`Overview ` | + :doc:`Full list of settings ` * **Applications:** - :doc:`Overview ` + :doc:`Overview ` * **Exceptions:** - :doc:`Overview ` + :doc:`Overview ` * **django-admin and manage.py:** - :doc:`Overview ` | - :doc:`Adding custom commands ` + :doc:`Overview ` | + :doc:`Adding custom commands ` * **Testing:** - :doc:`Introduction ` | - :doc:`Writing and running tests ` | - :doc:`Included testing tools ` | - :doc:`Advanced topics ` + :doc:`Introduction ` | + :doc:`Writing and running tests ` | + :doc:`Included testing tools ` | + :doc:`Advanced topics ` * **Deployment:** - :doc:`Overview ` | - :doc:`WSGI servers ` | - :doc:`ASGI servers ` | - :doc:`Deploying static files ` | - :doc:`Tracking code errors by email ` | - :doc:`Deployment checklist ` + :doc:`Overview ` | + :doc:`WSGI servers ` | + :doc:`ASGI servers ` | + :doc:`Deploying static files ` | + :doc:`Tracking code errors by email ` | + :doc:`Deployment checklist ` The admin ========= @@ -235,9 +235,9 @@ The admin Find all you need to know about the automated admin interface, one of Django's most popular features: -* :doc:`Admin site ` -* :doc:`Admin actions ` -* :doc:`Admin documentation generator` +* :doc:`Admin site ` +* :doc:`Admin actions ` +* :doc:`Admin documentation generator ` Security ======== @@ -245,13 +245,13 @@ Security Security is a topic of paramount importance in the development of web applications and Django provides multiple protection tools and mechanisms: -* :doc:`Security overview ` -* :doc:`Disclosed security issues in Django ` -* :doc:`Clickjacking protection ` -* :doc:`Cross Site Request Forgery protection ` -* :doc:`Cryptographic signing ` +* :doc:`Security overview ` +* :doc:`Disclosed security issues in Django ` +* :doc:`Clickjacking protection ` +* :doc:`Cross Site Request Forgery protection ` +* :doc:`Cryptographic signing ` * :ref:`Security Middleware ` -* :doc:`Content Security Policy ` +* :doc:`Content Security Policy ` Internationalization and localization ===================================== @@ -260,10 +260,10 @@ Django offers a robust internationalization and localization framework to assist you in the development of applications for multiple languages and world regions: -* :doc:`Overview ` | - :doc:`Internationalization ` | +* :doc:`Overview ` | + :doc:`Internationalization ` | :ref:`Localization ` | - :doc:`Localized web UI formatting and form input ` + :doc:`Localized web UI formatting and form input ` * :doc:`Time zones ` Performance and optimization @@ -272,14 +272,14 @@ Performance and optimization There are a variety of techniques and tools that can help get your code running more efficiently - faster, and using fewer system resources. -* :doc:`Performance and optimization overview ` +* :doc:`Performance and optimization overview ` Geographic framework ==================== -:doc:`GeoDjango ` intends to be a world-class geographic -web framework. Its goal is to make it as easy as possible to build GIS web -applications and harness the power of spatially enabled data. +:doc:`GeoDjango ` intends to be a world-class +geographic web framework. Its goal is to make it as easy as possible to build +GIS web applications and harness the power of spatially enabled data. Common web application tools ============================ @@ -288,36 +288,36 @@ Django offers multiple tools commonly needed in the development of web applications: * **Authentication:** - :doc:`Overview ` | - :doc:`Using the authentication system ` | - :doc:`Password management ` | - :doc:`Customizing authentication ` | - :doc:`API Reference ` -* :doc:`Caching ` -* :doc:`Logging ` -* :doc:`Sending emails ` -* :doc:`Syndication feeds (RSS/Atom) ` -* :doc:`Pagination ` -* :doc:`Messages framework ` -* :doc:`Serialization ` -* :doc:`Sessions ` -* :doc:`Sitemaps ` -* :doc:`Static files management ` -* :doc:`Data validation ` + :doc:`Overview ` | + :doc:`Using the authentication system ` | + :doc:`Password management ` | + :doc:`Customizing authentication ` | + :doc:`API Reference ` +* :doc:`Caching ` +* :doc:`Logging ` +* :doc:`Sending emails ` +* :doc:`Syndication feeds (RSS/Atom) ` +* :doc:`Pagination ` +* :doc:`Messages framework ` +* :doc:`Serialization ` +* :doc:`Sessions ` +* :doc:`Sitemaps ` +* :doc:`Static files management ` +* :doc:`Data validation ` Other core functionalities ========================== Learn about some other core functionalities of the Django framework: -* :doc:`Conditional content processing ` -* :doc:`Content types and generic relations ` -* :doc:`Flatpages ` -* :doc:`Redirects ` -* :doc:`Signals ` -* :doc:`System check framework ` -* :doc:`The sites framework ` -* :doc:`Unicode in Django ` +* :doc:`Conditional content processing ` +* :doc:`Content types and generic relations ` +* :doc:`Flatpages ` +* :doc:`Redirects ` +* :doc:`Signals ` +* :doc:`System check framework ` +* :doc:`The sites framework ` +* :doc:`Unicode in Django ` The Django open-source project ============================== @@ -326,23 +326,23 @@ Learn about the development process for the Django project itself and about how you can contribute: * **Community:** - :doc:`Contributing to Django ` | - :doc:`The release process ` | - :doc:`Team organization ` | - :doc:`The Django source code repository ` | - :doc:`Security policies ` | - :doc:`Mailing lists and Forum` + :doc:`Contributing to Django ` | + :doc:`The release process ` | + :doc:`Team organization ` | + :doc:`The Django source code repository ` | + :doc:`Security policies ` | + :doc:`Mailing lists and Forum ` * **Design philosophies:** - :doc:`Overview ` + :doc:`Overview ` * **Documentation:** - :doc:`About this documentation ` + :doc:`About this documentation ` * **Third-party distributions:** - :doc:`Overview ` + :doc:`Overview ` * **Django over time:** - :doc:`API stability ` | - :doc:`Release notes and upgrading instructions ` | - :doc:`Deprecation Timeline ` + :doc:`API stability ` | + :doc:`Release notes and upgrading instructions ` | + :doc:`Deprecation Timeline ` diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index c2dc0eee48..3cf2554926 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -4,8 +4,8 @@ Committing code This section is addressed to the mergers and to anyone interested in knowing how code gets committed into Django. If you're a community member who wants to -contribute code to Django, look at :doc:`writing-code/working-with-git` -instead. +contribute code to Django, look at +:doc:`/internals/contributing/writing-code/working-with-git` instead. .. _handling-pull-requests: diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index a6bb17ceeb..99f70b770a 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -54,7 +54,8 @@ Write some documentation Django's documentation is great but it can always be improved. Did you find a typo? Do you think that something should be clarified? Go ahead and suggest a -documentation patch! See also the guide on :doc:`writing-documentation`. +documentation patch! See also the guide on +:doc:`/internals/contributing/writing-documentation`. .. note:: diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index 295bf25ee5..62556dbfbb 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -387,7 +387,7 @@ Then, you can help out by: several that are useful for triaging tickets and reviewing proposals as suggested above. - You can also find more :doc:`new-contributors`. + You can also find more :doc:`/internals/contributing/new-contributors`. .. _Reports page: https://code.djangoproject.com/wiki/Reports diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 883ea8b9c2..e016543ac6 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -504,6 +504,6 @@ JavaScript style ================ For details about the JavaScript code style used by Django, see -:doc:`javascript`. +:doc:`/internals/contributing/writing-code/javascript`. .. _editorconfig: https://editorconfig.org/ diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index d1d5a8a32d..0dd1fd2041 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -15,7 +15,8 @@ If you are fixing a really trivial issue, for example changing a word in the documentation, the preferred way to provide the patch is using GitHub pull requests without a Trac ticket. -See the :doc:`working-with-git` for more details on how to use pull requests. +See the :doc:`/internals/contributing/writing-code/working-with-git` for more +details on how to use pull requests. "Claiming" tickets ================== @@ -109,19 +110,20 @@ requirements: * The code required to fix a problem or add a feature is an essential part of a solution, but it is not the only part. A good fix should also include a - :doc:`regression test ` to validate the behavior that has been - fixed and to prevent the problem from arising again. Also, if some tickets - are relevant to the code that you've written, mention the ticket numbers in - some comments in the test so that one can easily trace back the relevant - discussions after your patch gets committed, and the tickets get closed. + :doc:`regression test ` to + validate the behavior that has been fixed and to prevent the problem from + arising again. Also, if some tickets are relevant to the code that you've + written, mention the ticket numbers in some comments in the test so that one + can easily trace back the relevant discussions after your patch gets + committed, and the tickets get closed. * If the code adds a new feature, or modifies the behavior of an existing feature, the change should also contain documentation. When you think your work is ready to be reviewed, send :doc:`a GitHub pull -request `. -If you can't send a pull request for some reason, you can also use patches in -Trac. When using this style, follow these guidelines. +request `. If you can't +send a pull request for some reason, you can also use patches in Trac. When +using this style, follow these guidelines. * Submit patches in the format returned by the ``git diff`` command. diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index 7209bc0624..15ab7054aa 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -142,7 +142,7 @@ When you think your work is ready to be pulled into Django, you should create a pull request at GitHub. A good pull request means: * commits with one logical change in each, following the - :doc:`coding style `, + :doc:`coding style `, * well-formed messages for each commit: a summary line and then paragraphs wrapped at 72 characters thereafter -- see the :ref:`committing guidelines diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index 53c60d50db..23c1dc9622 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -31,7 +31,8 @@ own branch, called ``stable/A.B.x``, and bugfix/security releases will be issued from those branches. For more information about how the Django project issues new releases for -security purposes, please see :doc:`our security policies `. +security purposes, please see :doc:`our security policies +`. .. glossary:: diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index f8349df3e7..64bfd83d02 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1436,7 +1436,7 @@ default templates used by the :class:`ModelAdmin` views: The ``delete_queryset()`` method is given the ``HttpRequest`` and a ``QuerySet`` of objects to be deleted. Override this method to customize the deletion process for the "delete selected objects" :doc:`action - `. + `. .. method:: ModelAdmin.save_formset(request, form, formset, change) @@ -2055,7 +2055,7 @@ default templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_deleted_objects(objs, request) A hook for customizing the deletion process of the :meth:`delete_view` and - the "delete selected" :doc:`action `. + the "delete selected" :doc:`action `. The ``objs`` argument is a homogeneous iterable of objects (a ``QuerySet`` or a list of model instances) to be deleted, and ``request`` is the diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 7db103ed73..e23a7667f1 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -156,7 +156,7 @@ Geometry Lookups ---------------- Geographic queries with geometries take the following general form (assuming -the ``Zipcode`` model used in the :doc:`model-api`): +the ``Zipcode`` model used in the :doc:`/ref/contrib/gis/model-api`): .. code-block:: text @@ -192,7 +192,8 @@ used to pass a band index. On the right hand side, a tuple of the raster and band index can be specified. This results in the following general form for lookups involving rasters -(assuming the ``Elevation`` model used in the :doc:`model-api`): +(assuming the ``Elevation`` model used in the +:doc:`/ref/contrib/gis/model-api`): .. code-block:: text @@ -234,11 +235,10 @@ Distance Queries Introduction ------------ -Distance calculations with spatial data is tricky because, unfortunately, -the Earth is not flat. Some distance queries with fields in a geographic -coordinate system may have to be expressed differently because of -limitations in PostGIS. Please see the :ref:`selecting-an-srid` section -in the :doc:`model-api` documentation for more details. +Distance calculations with spatial data is tricky because, unfortunately, the +Earth is not flat. Some distance queries with fields in a geographic coordinate +system may have to be expressed differently because of limitations in PostGIS. +Please see the :ref:`selecting-an-srid` section for more details. .. _distance-lookups-intro: diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 4fb7bd6d56..af1cd439dc 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -85,7 +85,8 @@ queryset is calculated: express the value in the units of your choice. For example, ``city.distance.mi`` is the distance value in miles and ``city.distance.km`` is the distance value in kilometers. See - :doc:`measure` for usage details and the list of :ref:`supported_units`. + :doc:`/ref/contrib/gis/measure` for usage details and the list of + :ref:`supported_units`. ``GeometryDistance`` -------------------- diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 95367b798f..6df108af43 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -22,9 +22,9 @@ familiarize yourself with Django first. .. note:: - GeoDjango has additional requirements beyond what Django requires -- - please consult the :doc:`installation documentation ` - for more details. + GeoDjango has additional requirements beyond what Django requires -- please + consult the :doc:`installation documentation + ` for more details. This tutorial will guide you through the creation of a geographic web application for viewing the `world borders`_. [#]_ Some of the code @@ -49,8 +49,8 @@ Create a Spatial Database Typically no special setup is required, so you can create a database as you would for any other project. We provide some tips for selected databases: -* :doc:`install/postgis` -* :doc:`install/spatialite` +* :doc:`/ref/contrib/gis/install/postgis` +* :doc:`/ref/contrib/gis/install/spatialite` Create a New Project -------------------- @@ -305,7 +305,7 @@ Importing Spatial Data ====================== This section will show you how to import the world borders shapefile into the -database via GeoDjango models using the :doc:`layermapping`. +database via GeoDjango models using the :doc:`/ref/contrib/gis/layermapping`. There are many different ways to import data into a spatial database -- besides the tools included within GeoDjango, you may also use the following: @@ -531,11 +531,13 @@ Next, import the ``load`` module, call the ``run`` routine, and watch Try ``ogrinspect`` ------------------ + Now that you've seen how to define geographic models and import data with the -:doc:`layermapping`, it's possible to further automate this process with -use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` -command introspects a GDAL-supported vector data source (e.g., a shapefile) -and generates a model definition and ``LayerMapping`` dictionary automatically. +:doc:`/ref/contrib/gis/layermapping`, it's possible to further automate this +process with use of the :djadmin:`ogrinspect` management command. The +:djadmin:`ogrinspect` command introspects a GDAL-supported vector data source +(e.g., a shapefile) and generates a model definition and ``LayerMapping`` +dictionary automatically. The general usage of the command goes as follows: @@ -637,10 +639,10 @@ a ``contains`` lookup using the ``pnt_wkt`` as the parameter: Here, you retrieved a ``QuerySet`` with only one model: the border of the United States (exactly what you would expect). -Similarly, you may also use a :doc:`GEOS geometry object `. -Here, you can combine the ``intersects`` spatial lookup with the ``get`` -method to retrieve only the ``WorldBorder`` instance for San Marino instead -of a queryset: +Similarly, you may also use a :doc:`GEOS geometry object +`. Here, you can combine the ``intersects`` spatial +lookup with the ``get`` method to retrieve only the ``WorldBorder`` instance +for San Marino instead of a queryset: .. code-block:: pycon @@ -649,8 +651,8 @@ of a queryset: >>> WorldBorder.objects.get(mpoly__intersects=pnt) -The ``contains`` and ``intersects`` lookups are just a subset of the -available queries -- the :doc:`db-api` documentation has more. +The ``contains`` and ``intersects`` lookups are just a subset of the available +queries -- the :doc:`/ref/contrib/gis/db-api` documentation has more. .. _automatic-spatial-transformations: @@ -748,7 +750,7 @@ Geographic annotations GeoDjango also offers a set of geographic annotations to compute distances and several other operations (intersection, difference, etc.). See the -:doc:`functions` documentation. +:doc:`/ref/contrib/gis/functions` documentation. Putting your data on the map ============================ diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index bfc32c0d5c..39cfd8be1e 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -942,8 +942,8 @@ Configuring the rendering of a form's widgets .. attribute:: Form.default_renderer -Specifies the :doc:`renderer ` to use for the form. Defaults to -``None`` which means to use the default renderer specified by the +Specifies the :doc:`renderer ` to use for the form. +Defaults to ``None`` which means to use the default renderer specified by the :setting:`FORM_RENDERER` setting. You can set this as a class attribute when declaring your form or use the @@ -1070,9 +1070,9 @@ Customizing the error list format .. attribute:: renderer - Specifies the :doc:`renderer ` to use for ``ErrorList``. - Defaults to ``None`` which means to use the default renderer - specified by the :setting:`FORM_RENDERER` setting. + Specifies the :doc:`renderer ` to use for + ``ErrorList``. Defaults to ``None`` which means to use the default + renderer specified by the :setting:`FORM_RENDERER` setting. .. attribute:: field_id diff --git a/docs/ref/logging.txt b/docs/ref/logging.txt index 686145b673..0c2718331c 100644 --- a/docs/ref/logging.txt +++ b/docs/ref/logging.txt @@ -215,27 +215,28 @@ messages during filesystem inspection and event subscription processes. ``django.contrib.auth`` ~~~~~~~~~~~~~~~~~~~~~~~ -Log messages related to :doc:`contrib/auth`, particularly ``ERROR`` messages -are generated when a :class:`~django.contrib.auth.forms.PasswordResetForm` is -successfully submitted but the password reset email cannot be delivered due to -a mail sending exception. +Log messages related to :doc:`/ref/contrib/auth`, particularly ``ERROR`` +messages are generated when a +:class:`~django.contrib.auth.forms.PasswordResetForm` is successfully submitted +but the password reset email cannot be delivered due to a mail sending +exception. .. _django-contrib-gis-logger: ``django.contrib.gis`` ~~~~~~~~~~~~~~~~~~~~~~ -Log messages related to :doc:`contrib/gis/index` at various points: during the -loading of external GeoSpatial libraries (GEOS, GDAL, etc.) and when reporting -errors. Each ``ERROR`` log record includes the caught exception and relevant -contextual data. +Log messages related to :doc:`/ref/contrib/gis/index` at various points: during +the loading of external GeoSpatial libraries (GEOS, GDAL, etc.) and when +reporting errors. Each ``ERROR`` log record includes the caught exception and +relevant contextual data. .. _django-dispatch-logger: ``django.dispatch`` ~~~~~~~~~~~~~~~~~~~ -This logger is used in :doc:`signals`, specifically within the +This logger is used in :doc:`/ref/signals`, specifically within the :mod:`~django.dispatch.Signal` class, to report issues when dispatching a signal to a connected receiver. The ``ERROR`` log record includes the caught exception as ``exc_info`` and adds the following extra context: diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt index cfdbd0790a..80d1910b65 100644 --- a/docs/ref/models/conditional-expressions.txt +++ b/docs/ref/models/conditional-expressions.txt @@ -6,9 +6,9 @@ Conditional Expressions Conditional expressions let you use :keyword:`if` ... :keyword:`elif` ... :keyword:`else` logic within filters, annotations, aggregations, and updates. A -conditional expression evaluates a series of conditions for each row of a -table and returns the matching result expression. Conditional expressions can -also be combined and nested like other :doc:`expressions `. +conditional expression evaluates a series of conditions for each row of a table +and returns the matching result expression. Conditional expressions can also be +combined and nested like other :doc:`expressions `. The conditional expression classes ================================== diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index 0abd0e6a81..3d5a64f931 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -7,8 +7,8 @@ Database Functions The classes documented below provide a way for users to use functions provided by the underlying database as annotations, aggregations, or filters in Django. -Functions are also :doc:`expressions `, so they can be used and -combined with other expressions like :ref:`aggregate functions +Functions are also :doc:`expressions `, so they can be +used and combined with other expressions like :ref:`aggregate functions `. We'll be using the following model in examples of each function:: diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 121ed0f30a..6148f65363 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -340,7 +340,8 @@ extra attribute ``field_lower`` produced, roughly, from the following SQL: ... LOWER("db_table"."field") as "field_lower" -See :doc:`database-functions` for a list of built-in database functions. +See :doc:`/ref/models/database-functions` for a list of built-in database +functions. The ``Func`` API is as follows: @@ -582,7 +583,7 @@ Conditional expressions Conditional expressions allow you to use :keyword:`if` ... :keyword:`elif` ... :keyword:`else` logic in queries. Django natively supports SQL ``CASE`` -expressions. For more details see :doc:`conditional-expressions`. +expressions. For more details see :doc:`/ref/models/conditional-expressions`. ``Subquery()`` expressions -------------------------- diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index 5a9baa93a2..7d4b96432f 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -332,7 +332,8 @@ Models * :class:`~django.db.models.ImageField` now has a default :data:`~django.core.validators.validate_image_file_extension` validator. - (This validator moved to the form field in :doc:`Django 1.11.2 <1.11.2>`.) + (This validator moved to the form field in :doc:`Django 1.11.2 + `.) * Added support for time truncation to :class:`~django.db.models.functions.Trunc` functions. diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 8ca4726e92..513a7e5cbd 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -266,7 +266,7 @@ and in Django 1.5 will raise an ``ImproperlyConfigured`` exception. Everything else --------------- -Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added +Django :doc:`1.1 ` and :doc:`1.2 ` added lots of big ticket items to Django, like multiple-database support, model validation, and a session-based messages framework. However, this focus on big features came at the cost of lots of smaller diff --git a/docs/topics/auth/index.txt b/docs/topics/auth/index.txt index 10815945b1..9e57ab9239 100644 --- a/docs/topics/auth/index.txt +++ b/docs/topics/auth/index.txt @@ -75,7 +75,7 @@ models defined in your installed apps. Usage ===== -:doc:`Using Django's default implementation ` +:doc:`Using Django's default implementation ` * :ref:`Working with User objects ` * :ref:`Permissions and authorization ` @@ -84,6 +84,6 @@ Usage :doc:`API reference for the default implementation ` -:doc:`Customizing Users and authentication ` +:doc:`Customizing Users and authentication ` -:doc:`Password management in Django ` +:doc:`Password management in Django ` diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt index 6b2c435e1b..619636d8b9 100644 --- a/docs/topics/class-based-views/mixins.txt +++ b/docs/topics/class-based-views/mixins.txt @@ -5,8 +5,8 @@ Using mixins with class-based views .. caution:: This is an advanced topic. A working knowledge of :doc:`Django's - class-based views` is advised before exploring these - techniques. + class-based views ` is advised before + exploring these techniques. Django's built-in class-based views provide a lot of functionality, but some of it you may want to use separately. For instance, you may @@ -120,9 +120,9 @@ but the main one that most people are going to use is ``/_detail.html``. The ``_detail`` part can be changed by setting :attr:`~django.views.generic.detail.SingleObjectTemplateResponseMixin.template_name_suffix` -on a subclass to something else. (For instance, the :doc:`generic edit -views` use ``_form`` for create and update views, and -``_confirm_delete`` for delete views.) +on a subclass to something else. (For instance, the :doc:`generic edit views +` use ``_form`` for create and +update views, and ``_confirm_delete`` for delete views.) ``ListView``: working with many Django objects ---------------------------------------------- @@ -213,8 +213,8 @@ in the subclass. However if we want our processing to work on a particular object, identified from the URL, we'll want the functionality provided by :class:`~django.views.generic.detail.SingleObjectMixin`. -We'll demonstrate this with the ``Author`` model we used in the -:doc:`generic class-based views introduction`. +We'll demonstrate this with the ``Author`` model we used in the :doc:`generic +class-based views introduction `. .. code-block:: python :caption: ``views.py`` @@ -390,11 +390,11 @@ increasingly complex as you try to do so, and a good rule of thumb is: .. hint:: - Each of your views should use only mixins or views from one of the - groups of generic class-based views: :doc:`detail, - list`, :doc:`editing` and - date. For example it's fine to combine - :class:`TemplateView` (built in view) with + Each of your views should use only mixins or views from one of the groups + of generic class-based views: :doc:`detail, list + `, :doc:`editing + ` and date. For example it's + fine to combine :class:`TemplateView` (built in view) with :class:`~django.views.generic.list.MultipleObjectMixin` (generic list), but you're likely to have problems combining ``SingleObjectMixin`` (generic detail) with ``MultipleObjectMixin`` (generic list). diff --git a/docs/topics/testing/index.txt b/docs/topics/testing/index.txt index 1192b8264e..ef96895fb7 100644 --- a/docs/topics/testing/index.txt +++ b/docs/topics/testing/index.txt @@ -22,11 +22,11 @@ it should be doing. The preferred way to write tests in Django is using the :mod:`unittest` module built-in to the Python standard library. This is covered in detail in the -:doc:`overview` document. +:doc:`/topics/testing/overview` document. You can also use any *other* Python test framework; Django provides an API and tools for that kind of integration. They are described in the -:ref:`other-testing-frameworks` section of :doc:`advanced`. +:ref:`other-testing-frameworks` section of :doc:`/topics/testing/advanced`. .. toctree:: :maxdepth: 1