Re: [Django] #37217: Contributing tutorial shows the django next version but it's hardcoded and could use some automated updating

[Django]

#37217: Contributing tutorial shows the django next version but it's hardcoded and
could use some automated updating
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: django_next_version | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by blighj):

* has_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/37217#comment:19>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37217: Contributing tutorial shows the django next version but it's hardcoded and
could use some automated updating
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: django_next_version | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mike Edmunds):

''If'' we're going to try to automate the version in the tutorial, I think
SnippyCodes'
[https://github.com/django/django/commit/84408a680b53747d4853550be3c8c212d3bd84ea
original change] to replace `"|django_next_version|"` in Sphinx's source-
read hook is about as simple, stable, and maintainable as it can get:
- The [https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html
#event-source-read source-read event is documented] for exactly this sort
of transformation.
- It's been available since Sphinx 0.5 (2009), and the ''only'' change
since then was in 7.0–7.5 (when source-read was briefly also emitted for
`.. include::` files too; that wouldn't have been a breaking change for
this code).
- Our event callback would be `str.replace()`. No regular expressions, no
filtering for specific filenames. No magic.

The downside (as Carlton pointed out) is the tutorial source ends up with
lines like these, which are less readable than before:

{{{#!text
--- a/docs/releases/|django_next_version|.txt
+++ b/docs/releases/|django_next_version|.txt
}}}

We could use something other than `|django_next_version|` as the
substitution string, to try to make the source more readable:
- E.g., `N.M` so the source could read `a/docs/releases/N.M.txt`, etc.
That works for now, if you restrict the replacement to word boundaries
(`r"\bN\.M\b"` doesn't match any existing docs source). But it might cause
unintended replacements in future edits. (`X.Y` and `A.B` already appear
in the docs.)
- Or something like `|N.M|` or `|X.Y|` to minimize chances of accidental
replacement. (Also, the pipe chars maybe help convey there's reST
substitution involved.) I'm not convinced that would be more meaningful
than `|django_next_version|` in the source, but it is shorter.

Like I said above, I don't feel that strongly about automating it. But if
we do want to, this would be my recommendation.
--
Ticket URL: <https://code.djangoproject.com/ticket/37217#comment:20>

[Django]

#37217: Contributing tutorial shows the django next version but it's hardcoded and
could use some automated updating
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: django_next_version | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by blighj):

Related to this
https://docs.djangoproject.com/en/6.0/ref/django-admin/#envvar-
DJANGO_RUNSERVER_HIDE_WARNING

django-admin.txt has a block that renders with `|version| ` in the url, is
that a known bug?
{{{
WARNING: This is a development server. Do not use it in a production
setting. Use a production WSGI or ASGI server instead.
For more information on production servers see:
https://docs.djangoproject.com/en/|version|/howto/deployment/
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37217#comment:21>

[Django]

#37217: Contributing tutorial shows the django next version but it's hardcoded and
could use some automated updating
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: django_next_version | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mike Edmunds):

Replying to [comment:21 blighj]:

> django-admin.txt has a block that renders with `|version| ` in the url,
is that a known bug?
> {{{
> WARNING: This is a development server. Do not use it in a production
setting. Use a production WSGI or ASGI server instead.
> For more information on production servers see:
https://docs.djangoproject.com/en/|version|/howto/deployment/
> }}}

Good catch. It's probably not necessary for the docs to quote the entire
warning message there. I'd suggest removing the last sentence to avoid
more complicated substitution logic (`|version|` would need to resolve to
`dev` for pre-alpha versions).
--
Ticket URL: <https://code.djangoproject.com/ticket/37217#comment:22>