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, including a link to the original unstructured version
(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.
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.
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 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:
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
That’s not quite right. We have the autosectionlabel extension 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 --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.
) using 
