[Django] #18448: Rename all documentation files to have .rst extension
Django
--------------------------------------+--------------------
Reporter: mjtamlyn | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.4
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+--------------------
All of the docs files are written in reStructuredText, and should probably
have the correct extension. Whilst of course one can configure a text
editor to use rst syntax highlighting etc, for the new contributor they
may not realise to do this.
To be honest, when I first downloaded the docs I was unsure whether the
.txt files were actually the docs given that Sphinx docs are written in
rst.
Git understands renaming files pretty well, so it should be ok to do this
even for people with edits to the file - they should all merge in
correctly (with a bit of luck).
--
Ticket URL: <https://code.djangoproject.com/ticket/18448>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: mjtamlyn | Owner: nobody
Type: | Status: closed
Cleanup/optimization | Version: 1.4
Component: Documentation | Resolution: wontfix
Severity: Normal | Triage Stage:
Keywords: | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Changes (by jacob):
* status: new => closed
* needs_better_patch: => 0
* resolution: => wontfix
* needs_tests: => 0
* needs_docs: => 0
Comment:
I see the reasoning here, but I'm going to reject this one. It's
essentially one of those things that we can't get right either way. If we
use `.rst`, the advantages are as you said, but many OSes won't know what
to do with `.rst` and so we'll get people asking to rename to `.txt` so
that the files open in their text editors. At a certain point you just
gotta make a call, and I'm calling it for `.txt`.
--
Ticket URL: <https://code.djangoproject.com/ticket/18448#comment:1>
Django
Reporter: Marc Tamlyn | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.4
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mike Lissner):
I just did some work on documentation today and I found the use if txt
extensions instead of rst extension to be a bit frustrating. For example,
my editor couldn't treat these as ReStructured Text, and then when I was
writing my pull request, I couldn't review my work in Github either.
Similarly, for whomever reviews my PR, they won't be able to review it on
Github either, and will have to do so on their laptop, which is an extra
step for them.
I guess I understand the explanation from nine years ago that some people
won't be able to open rst files in their editor, but I think if Github
supports these natively, we can assume that just about everybody
contributing documentation would support them natively too.
Should we reconsider this one? I'd happily make a little PR to rename
files if so.
--
Ticket URL: <https://code.djangoproject.com/ticket/18448#comment:2>
Django
Reporter: Marc Tamlyn | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Comment (by Mike Edmunds):
GitHub also supports `.rst.txt` extensions for rendering reStructuredText
source with previews and syntax highlighting:
https://github.com/medmunds/django/blob/rename-
docs/docs/intro/overview.rst.txt. That would address the concerns about
opening in text editors, so might be a reasonable compromise.
That said, I'd still argue for just going with `.rst` as the friendliest
for newcomers in online editors and IDEs. Neither PyCharm nor VS Code
recognize `.rst.txt` by default—they just open it as an ordinary text file
(and VS Code won't suggest installing a reST plugin). You can add file
type overrides to make it work, but if you've never heard of reST that
probably won't occur to you.
[I've also tried a
[https://github.com/django/django/pull/19279#issuecomment-2734378910
.gitattributes linguist override] on docs/!**.txt, with poor results.]
--
Ticket URL: <https://code.djangoproject.com/ticket/18448#comment:3>
Django
Reporter: Marc Tamlyn | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Comment (by Adam Johnson):
Thanks for the input both. I would love to do this too, but I think
there's a chance for some disruption, so I’ve opened
[https://forum.djangoproject.com/t/rename-documentation-files-from-txt-to-
rst/39699 a forum thread] to resolve the discussion before we enact the
change.
--
Ticket URL: <https://code.djangoproject.com/ticket/18448#comment:4>