RST vs MD

[sdgathman]

Github wants markdown, PyPi wants RST. My attempt to make README.md compatible with both failed. Do we maintain both README.md and README.rst ? Is there a convert ? Is there a previewer (web or otherwise) for RST? Can I reupload versions to debug README to test.pypi.org? So many questions.

[kitterma]

It's a distutils versus setuptools thing I think. You've got long_description_content_type='text/markdown', in setup.py, but it's not recognized (with twine check I get:

Checking distribution dist/pyspf-2.0.14.tar.gz: warning: long_description_content_type missing. defaulting to text/x-rst.

If I switch to setuptools, the error goes away:

diff --git a/setup.py b/setup.py
index a64521c..35843f1 100755
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
#!/usr/bin/python

-from distutils.core import setup
+from setuptools import setup
import sys

DESC = """SPF (Sender Policy Framework) implemented in Python."""

If we change to setuptools, we can also specify dependencies in setup.py so users don't have to install them by hand. If you're OK wiith it, I'll make the change.

[sdgathman]

Yes, I can change the type to rst, but github wants markdown. The setuptools aren't the issue. Unless you're saying pypi does support markdown, but twine just syntax checks as RST.

[sdgathman]

Currently, the content type says markdown, and the file is named README.md - and yet pypi still interprets it as RST. So it is pretty clear that the title of this issue is accurate. We have to support two different markdown syntaxes. Or adopt a subset that works with both. Is there a preformatted syntax that works with both?

[kitterma]

Pypi wants rst because of the difference in the PKG-INFO file in the sdist. Here's the diff going from Pkg-Info generated by distutils and setuptools:

diff -ruN pyspf-2.0.14/PKG-INFO pyspf.egg-info/PKG-INFO
--- pyspf-2.0.14/PKG-INFO 2020-01-02 22:25:23.000000000 -0500
+++ pyspf.egg-info/PKG-INFO 2020-01-02 22:24:39.477610691 -0500
@@ -1,10 +1,12 @@
-Metadata-Version: 1.1
+Metadata-Version: 2.1
Name: pyspf
Version: 2.0.14
Summary: SPF (Sender Policy Framework) implemented in Python.
Home-page: https://github.com/sdgathman/pyspf/
-Author: Stuart D. Gathman
-Author-email: stuart@gathman.org
+Author: Terence Way
+Author-email: terry@wayforward.net
+Maintainer: Stuart D. Gathman
+Maintainer-email: stuart@gathman.org
License: Python Software Foundation License
Description: SPF
===
@@ -220,3 +222,4 @@
Classifier: Topic :: Communications :: Email :: Filters
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/markdown

Note the addition of Description-Content-Type when generated with setuptools. If you want to use Markdown for both Github and Pypi, that will solve it.

[kitterma]

The Python community has pretty well left distutils behind and focused on setuptools, so even though there are a few things about it I find annoying, it's the future. We may as well switch and solve this.