[SR-7454] .rst files are extremely developer-unfriendly

[davedelong]

Previous ID	SR-7454
Radar	None
Original Reporter	@davedelong
Type	Bug

Additional Detail from JIRA

Votes	1
Component/s	Compiler
Labels	Bug, Documentation
Assignee	@MaxDesiatov
Priority	Medium

md5: 42c38599a264a7abead082e305ce5b36

Issue Description:

For someone who's wanting to learn about Swift, they might consider going to the docs folder to learn more, and especially the "Lexicon" file.

However, they're greeted by a wall of .rst files, and macOS has no clue what .rst files are. Quicklooking on them just greets you with a blank file icon and no idea what the contents are. An intrepid person might think about popping a file open in their text-editor-of-choice, but it's not hard to imagine that someone might assume they'd need some crazy special tool in order to use these files and give up to go look somewhere else.

Please use a sane and common file format for the docs.

[belkadan]

We had a project to convert them to Markdown but it stalled because it would lose semantic information. At this point someone should probably just pick that up again and do the best job they can.

[davedelong]

Agreed; I heard about that from CodaFi (JIRA User), and went and found it: #11053