Re: [Django] #18448: Rename all documentation files to have .rst extension

[Django]

#18448: Rename all documentation files to have .rst extension
-+-
 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
  Needs tests:  0|  Patch needs improvement:  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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/066.1393e7c5b42d87e68c5e74e82d903164%40djangoproject.com.

Re: [Django] #18448: Rename all documentation files to have .rst extension

[Django]

#18448: Rename all documentation files to have .rst extension
-+-
 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
Easy pickings:  0|UI/UX:  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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to 
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-updates?hl=en.

[Django] #18448: Rename all documentation files to have .rst extension

[Django]

#18448: Rename all documentation files to have .rst extension
--+
 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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to 
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-updates?hl=en.