Rename all documentation files to have .rst extension

[Marc Tamlyn]

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).

[Jacob]

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.

[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.

[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 ​.gitattributes linguist override on docs/**.txt, with poor results due to a ​GitHub preview rendering bug.]

[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 ​a forum thread to resolve the discussion before we enact the change.