Use .rst as the file extension for reST-based PEPs

[brettcannon]

Requires not only renaming all relevant files but also updating code to accept the file extension. As part of this we can probably consider dropping the Content-Type as it will be known from the file extension (although others may disagree).

This will allow for rich rendering of the reST-based PEPS by GitHub.

[ncoghlan]

#32 covers supporting .rst as an extension in the Makefile and PEP 0 generator

[ncoghlan]

@berkerpeksag mentioned in #116 that the .rst extension isn't supported by the python.org importer yet.

I think that may be the only remaining barrier to a bulk rename of the existing text/x-rst PEPs.

[brettcannon]

That's been my assumption as well about where things stand.

[brettcannon]

This issue is also dependent on #4 .

[brettcannon]

Looks like www.python.org/dev/peps/ will now display PEPs with a .rst ending as demonstrated by PEP 550! The next problem is that the source link at the end of PEPs don't work for PEPs that end in .rst.

[berkerpeksag]

The problem is the converter doesn't know anything about the source file so we probably need to guess the extension (maybe do a HEAD request to .txt first; if status is not 200; try .rst?)

[brettcannon]

What I'm expecting is once #4 is done we can update the converter to assume .rst and then start moving all the file names over so it won't matter what the assumption is.

[gvanrossum]

Hm... The source link thing is sad. Where's the code for the converter?

[ncoghlan]

This is the offending line in the web app: https://github.com/python/pythondotorg/blob/master/peps/converters.py#L184

I'm thinking it may make sense to move that part out of the web app and into pep2html.py.

[gvanrossum]

Oh, that's a good idea.

[Mariatta]

I learned in #462 that renaming a file on GitHub has a side effect of not being able to view the file's complete history. For example, after pep-0008.txt was renamed to pep-0008.rst, GitHub is only showing the history of pep-0008.rst as if it is a new file.

(The "History" I'm referring to is the button on GitHub when you're viewing the file: https://github.com/python/peps/blob/master/pep-0008.txt:)

Using the command line, git log pep-0008.rst only shows the revision history after the rename.
To get the full history of PEP 8 since the very beginning, we need to do git log --follow pep-0008.rst.
To me, not being able to view the full revision history on GitHub is a major inconvenience. I reverted that PR so everything is back to *.txt again.

[gvanrossum]

Good call Mariatta! That's a really dumb GitHub feature. But so be it.

[Rosuav]

Personally, I just use the command-line git tools, or gitk. If GitHub can't track across renames, that's their problem, not ours.

[ncoghlan]

I use the online history browser to check "When did such & such a change happen?", so losing annotations would be more annoying than not having inline rendering.

So using .rst for new PEPs, and leaving existing ones alone sounds like a reasonable compromise to me (unless/until GitHub update their history browser and annotation display to handle renames)

[berkerpeksag]

So using .rst for new PEPs, and leaving existing ones alone sounds like a reasonable compromise to me (unless/until GitHub update their history browser and annotation display to handle renames)

+1.

[brettcannon]

Do realize that leaving old PEPs as-is will still require a code change as the link back to the PEP source will still be broken (right now it blindly assumes it's a .txt file).

[ncoghlan]

Right, we should still pull that snippet out of the website code and move it into pep2html.py

[Mariatta]

The link back to the PEP source has been fixed in python/pythondotorg#1195.

[brettcannon]

So is this considered done at this point then?

[ncoghlan]

Aye, looks done to me - if we find anything else missing, it can become a new issue.

[ncoghlan]

Thanks to all involved in getting this done!

[pradyunsg]

Relevant here: isaacs/github#900