From 3dfdb52b6fab1d03006fe30f4ebc44bf3c22103b Mon Sep 17 00:00:00 2001 From: Andy Chosak Date: Tue, 3 Aug 2021 10:31:54 -0400 Subject: [PATCH] Fix broken references in Pages topic documentation The "Page models" documentation page in the Wagtail usage guide has several broken links (see current page at https://docs.wagtail.io/en/stable/topics/pages.html). These links work when developing the documentation locally, but not when served on ReadTheDocs (docs.wagtail.io) The broken links are all of the form /some/page.html#anchor - somehow this format doesn't translate properly to get the necessary RTD prefix (for example /en/stable/). I've modified these links to use RST references, which will also make them more robust to future changes. --- docs/reference/pages/model_reference.rst | 2 + docs/topics/pages.md | 58 ++++++++++++++++-------- 2 files changed, 40 insertions(+), 20 deletions(-) diff --git a/docs/reference/pages/model_reference.rst b/docs/reference/pages/model_reference.rst index 500e34a302..743bea6dee 100644 --- a/docs/reference/pages/model_reference.rst +++ b/docs/reference/pages/model_reference.rst @@ -170,6 +170,8 @@ In addition to the model fields provided, ``Page`` has many properties and metho .. automethod:: get_url + .. automethod:: get_full_url + .. autoattribute:: full_url .. automethod:: relative_url diff --git a/docs/topics/pages.md b/docs/topics/pages.md index e879977708..70b64bc88d 100644 --- a/docs/topics/pages.md +++ b/docs/topics/pages.md @@ -1,6 +1,8 @@ # Page models -Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the [`wagtail.core.models.Page`](/reference/pages/model_reference.html#wagtail.core.models.Page) class. +```eval_rst +Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the :class:`wagtail.core.models.Page` class. +``` As all page types are Django models, you can use any field type that Django provides. See [Model field reference](https://docs.djangoproject.com/en/3.1/ref/models/fields/) for a complete list of field types you can use. Wagtail also provides `wagtail.core.fields.RichTextField` which provides a WYSIWYG editor for editing rich-text content. @@ -134,27 +136,31 @@ Here's a summary of the `EditHandler` classes that Wagtail provides out of the b These allow editing of model fields. The `FieldPanel` class will choose the correct widget based on the type of the field, though `StreamField` fields need to use a specialised panel class. -- [`FieldPanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.FieldPanel) -- [`StreamFieldPanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.StreamFieldPanel) +```eval_rst +- :class:`~wagtail.admin.edit_handlers.FieldPanel` +- :class:`~wagtail.admin.edit_handlers.StreamFieldPanel` +``` **Structural** These are used for structuring fields in the interface. -- [`MultiFieldPanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.MultiFieldPanel) - For grouping similar fields together -- [`InlinePanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.InlinePanel) - For inlining child models -- [`FieldRowPanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.FieldRowPanel) - For organising multiple fields into a single row +```eval_rst +- :class:`~wagtail.admin.edit_handlers.MultiFieldPanel` +- :class:`~wagtail.admin.edit_handlers.InlinePanel` +- :class:`~wagtail.admin.edit_handlers.FieldRowPanel` +``` **Chooser** `ForeignKey` fields to certain models can use one of the below `ChooserPanel` classes. These add a nice modal chooser interface, and the image/document choosers also allow uploading new files without leaving the page editor. -- [`PageChooserPanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.PageChooserPanel) -- [`ImageChooserPanel`](/reference/pages/panels.html#wagtail.images.edit_handlers.ImageChooserPanel) -- [`DocumentChooserPanel`](/reference/pages/panels.html#wagtail.documents.edit_handlers.DocumentChooserPanel) -- [`SnippetChooserPanel`](/reference/pages/panels.html#wagtail.snippets.edit_handlers.SnippetChooserPanel) - ```eval_rst +- :class:`~wagtail.admin.edit_handlers.PageChooserPanel` +- :class:`~wagtail.images.edit_handlers.ImageChooserPanel` +- :class:`~wagtail.documents.edit_handlers.DocumentChooserPanel` +- :class:`~wagtail.snippets.edit_handlers.SnippetChooserPanel` + .. note:: In order to use one of these choosers, the model being linked to must either be a page, image, document or snippet. @@ -211,7 +217,9 @@ super().get_url_parts(*args, **kwargs) While you could pass only the `request` keyword argument, passing all arguments as-is ensures compatibility with any future changes to these method signatures. -For more information, please see [`wagtail.core.models.Page.get_url_parts`](/reference/pages/model_reference.html#wagtail.core.models.Page.get_url_parts). +```eval_rst +For more information, please see :meth:`wagtail.core.models.Page.get_url_parts`. +``` #### Obtaining URLs for page instances @@ -220,9 +228,15 @@ The `Page.get_url(request)` method can be called whenever a page URL is needed. A common use case for `get_url(request)` is in any custom template tag your project may include for generating navigation menus. When writing such a custom template tag, ensure that it includes `takes_context=True` and use `context.get('request')` to safely pass the request or `None` if no request exists in the context. -For more information, please see [`wagtail.core.models.Page.get_url`](/reference/pages/model_reference.html#wagtail.core.models.Page.get_url). +```eval_rst +For more information, please see :meth:`wagtail.core.models.Page.get_url`. +``` -In the event a full URL (including the protocol and domain) is needed, `Page.get_full_url(request)` can be used instead. Whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information. For more information, please see [`wagtail.core.models.Page.get_full_url`](/reference/pages/model_reference.html#wagtail.core.models.Page.get_full_url). +In the event a full URL (including the protocol and domain) is needed, `Page.get_full_url(request)` can be used instead. Whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information. + +```eval_rst +For more information, please see :meth:`wagtail.core.models.Page.get_full_url`. +``` ## Template rendering @@ -344,10 +358,10 @@ Wagtail can nest the content of other models within the page. This is useful for Each inline model requires the following: -- It must inherit from [`wagtail.core.models.Orderable`](/reference/pages/model_reference.html#wagtail.core.models.Orderable) +```eval_rst +- It must inherit from :class:`wagtail.core.models.Orderable` - It must have a `ParentalKey` to the parent model -```eval_rst .. note:: django-modelcluster and ParentalKey The model inlining feature is provided by `django-modelcluster `_ and the ``ParentalKey`` field type must be imported from there: @@ -378,7 +392,9 @@ class BlogPageRelatedLink(Orderable): ] ``` -To add this to the admin interface, use the [`InlinePanel`](/reference/pages/panels.html#wagtail.admin.edit_handlers.InlinePanel) edit panel class: +```eval_rst +To add this to the admin interface, use the :class:`~wagtail.admin.edit_handlers.InlinePanel` edit panel class: +``` ```python content_panels = [ @@ -394,11 +410,13 @@ The first argument must match the value of the `related_name` attribute of the ` Wagtail uses Django's [multi-table inheritance](https://docs.djangoproject.com/en/3.1/topics/db/models/#multi-table-inheritance) feature to allow multiple page models to be used in the same tree. -Each page is added to both Wagtail's builtin [`Page`](/reference/pages/model_reference.html#wagtail.core.models.Page) model as well as its user-defined model (such as the `BlogPage` model created earlier). +```eval_rst +Each page is added to both Wagtail's builtin :class:`~wagtail.core.models.Page` model as well as its user-defined model (such as the `BlogPage` model created earlier). +``` -Pages can exist in Python code in two forms, an instance of [`Page`](/reference/pages/model_reference.html#wagtail.core.models.Page) or an instance of the page model. +Pages can exist in Python code in two forms, an instance of `Page` or an instance of the page model. -> When working with multiple page types together, you will typically use instances of Wagtail's [`Page`](/reference/pages/model_reference.html#wagtail.core.models.Page) model, which don't give you access to any fields specific to their type. +When working with multiple page types together, you will typically use instances of Wagtail's `Page` model, which don't give you access to any fields specific to their type. ```python # Get all pages in the database