# Using :ref: rather than :doc:

**URL:** <https://forum.djangoproject.com/t/using-rather-than/35204>\
**Category:** Django Internals\
**Created:** [September 28, 2024, 6:18pm UTC](https://forum.djangoproject.com/t/using-rather-than/35204 "2024-09-28T18:18:44Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![evildmp](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/evildmp/32/23487_2.png) [@evildmp](https://forum.djangoproject.com/u/evildmp)\
**Post date:** [September 28, 2024, 6:18pm UTC](https://forum.djangoproject.com/t/using-rather-than/35204/1 "2024-09-28T18:18:44Z")

</div>

At the DjangoCon US sprints, I began some work to improve main landing pages. I started with the how-to guides landing page, which right now is a not very useful list in more-or-less alphabetical order by filename.

- [pull request](https://github.com/django/django/pull/18626), including a link to the original unstructured version
- [New structured version](https://django--18626.org.readthedocs.build/en/18626/howto/index.html)

(There will need to be some follow-on work eventually, because one thing this restructuring does is expose some completely different problems within that section, but that’s another story.)

It’s apparent that Django’s use of `:doc:` to link to pages, rather than using a `:ref:` to a target placed at the top of the page, makes restructuring and refactoring unnecessarily complex and error-prone.

If we used `:ref:`, then there would be no need to amend any of the hyperlinks. Using `:doc:` means that every one has to be hunted down. (An additional complication is that `:doc:` is used inconsistently - sometimes a relative path is given, sometimes an absolute path.)

It will be necessary though to establish some conventions, to make them more useful (for example, the _Advanced testing topic_ should be labelled `topics-testing-advanced`).

`:ref:` has the additional benefit that it can provide a more semantic label than a page’s filename - `topics-testing-advanced` tells you more than `advanced.txt` does.

Using `:ref:` means that links point to labelled information - not just places. It’s harder to merge two pages or to split one if you’re pointing at `:doc:`s, whereas you simply don’t need to worry about it if the _information_ is labelled.

I don’t suggest a big effort to convert links, but I think that using `:ref:` should become the standard, and when there’s undisruptive opportunity to change a `:doc:` to a `:ref:` we should take it. It’s going to make managing a large documentation set easier.

---

<div class="post-metadata">

**Author:** ![carltongibson](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/carltongibson/32/267_2.png) [@carltongibson](https://forum.djangoproject.com/u/carltongibson)\
**Post date:** [September 29, 2024, 9:19am UTC](https://forum.djangoproject.com/t/using-rather-than/35204/2 "2024-09-29T09:19:41Z")

</div>

I think (😬) using `:ref:` has been generally favoured for a long-time, not least because when something moves the `:ref:` remains valid where the `:doc:` does not.

Adding a note to that effect to the [Guidelines for reStructuredText files](https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#guidelines-for-restructuredtext-files) guide would be worthwhile.

---

<div class="post-metadata">

**Author:** ![sarahboyce](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/sarahboyce/32/12734_2.png) [@sarahboyce](https://forum.djangoproject.com/u/sarahboyce)\
**Post date:** [June 27, 2025, 7:35am UTC](https://forum.djangoproject.com/t/using-rather-than/35204/3 "2025-06-27T07:35:21Z")

</div>

For background, right now only 5 of all of our existing docs pages start with a `:ref:`. When we create a new page in the docs (such as release notes), we are not adding a ref as standard practice.

To me, using `:doc:` when referring to that page is semantically more correct than `:ref:`. Using `:doc:` you are pointing to that page rather than specific information on the page (in which case `:ref:` would be more appropriate).

The file path and url are tightly coupled. A file named `docs/ref/clickjacking.txt` which has the url [Clickjacking Protection | Django documentation | Django](https://docs.djangoproject.com/en/dev/ref/clickjacking/) should largely still be about clickjacking even if there are lots of changes to these docs. So if you had a reference to this document on Clickjacking, I don’t see why this would become invalid.

That these `:doc:` links break when the page is moved/removed is not necessarily a bad thing. It’s easy to spot as this errors when building the docs with:

```auto
django/docs/faq/general.txt:67: WARNING: unknown document: 'somewhere-invlaid' [ref.doc]

```

But it also highlights that moving or removing a document would break links that might be shared or used by our users. This shouldn’t be an action that is taken lightly.

> (An additional complication is that `:doc:` is used inconsistently - sometimes a relative path is given, sometimes an absolute path.)

I agree this is inconsistent and we should probably always use an absolute path

---

<div class="post-metadata">

**Author:** ![adamchainz](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/adamchainz/32/26_2.png) [@adamchainz](https://forum.djangoproject.com/u/adamchainz)\
**Post date:** [June 27, 2025, 1:36pm UTC](https://forum.djangoproject.com/t/using-rather-than/35204/4 "2025-06-27T13:36:19Z")

</div>

I follow Sarah’s reasoning here: no need to introduce `:ref:` where `:doc:` makes sense, semantically.

> [@sarahboyce](#):
>
> I agree this is inconsistent and we should probably always use an absolute path

THis makes sense to me.

I made a draft PR that patches Sphinx to require absolute targets for `:doc:` - [Enforced absolute targets for :doc: in docs. by adamchainz · Pull Request #19599 · django/django · GitHub](https://github.com/django/django/pull/19599) . I fixed a bunch of instances, about 60 more remain, if we want to take that path.

What do y’all think?

---

<div class="post-metadata">

**Author:** ![carltongibson](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/carltongibson/32/267_2.png) [@carltongibson](https://forum.djangoproject.com/u/carltongibson)\
**Post date:** [June 27, 2025, 2:33pm UTC](https://forum.djangoproject.com/t/using-rather-than/35204/5 "2025-06-27T14:33:53Z")

</div>

> [@sarahboyce](#):
>
> For background, right now only 5 of all of our existing docs pages start with a `:ref:`.

That’s not quite right. We have the [`autosectionlabel` extension](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#module-sphinx.ext.autosectionlabel) enabled, which generates page-prefixed labels up to the second header level.

So an example, duplicating the `:doc:` link we have in the 6.0 release notes:

```diff
diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt
index 118ad43cc9..b4019ee437 100644
--- a/docs/releases/6.0.txt
+++ b/docs/releases/6.0.txt
@@ -15,6 +15,9 @@ want to be aware of when upgrading from Django 5.2 or earlier. We've
 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
 project.

+Example of another link straight to a section:
+:ref:`howto/upgrade-version:How to upgrade Django to a newer version`.
+
 Python compatibility
 ====================

```

The syntax there is the page path `howto/upgrade-python`, a colon `:` and then the header text `How to upgrade Django to a newer version`.

You can see the correct link is generated:

 ![Screenshot of the edited docs showing the new link](https://us1.discourse-cdn.com/flex026/uploads/djangoproject/original/3X/0/2/02d9eba3801dbf48ce23887b759e8838bdc755ac.png)

And using this continues to give the warning if things go missing etc.

---

<div class="post-metadata">

**Author:** ![nessita](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nessita/32/12194_2.png) [@nessita](https://forum.djangoproject.com/u/nessita)\
**Post date:** [August 28, 2025, 4:50pm UTC](https://forum.djangoproject.com/t/using-rather-than/35204/6 "2025-08-28T16:50:08Z")

</div>

> [@adamchainz](#):
>
> I made a draft PR that patches Sphinx to require absolute targets for `:doc:` - [Enforced absolute targets for :doc: in docs. by adamchainz · Pull Request #19599 · django/django · GitHub](https://github.com/django/django/pull/19599)

This PR was taken over and pushed to the final line. Now merged! 🤩
