Opened 3 years ago

Closed 3 years ago

#18448 closed Cleanup/optimization (wontfix)

Rename all documentation files to have .rst extension

Reported by: mjtamlyn Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Change History (1)

comment:1 Changed 3 years ago by jacob

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

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.

Note: See TracTickets for help on using tickets.
Back to Top