README in markdown instead of .rst?

[darribas]

While working on the Notebooks book project, I've realised that the README file for this project is structured in .rst. Is there a reason for this? If not, would it be possible to convert it markdown? I'm currently converting with pandoc but would probably be better to be consistent across de federation?

[weikang9009]

I do not think there is a specific reason for only having the README file in .rst. But if .md is preferred in the notebooks book project and the meta package building, it makes sense to convert README.rst to .md. I also think it might make sense to require README.md in pysal submodules and list it in the submodule-contract since other packages such as spreg has README.rst only as well. Would it also be reasonable to require README.md only in submodules as README.rst seems to be just a duplicate in most pysal packages which have both files (e.g. spaghetti, giddy)?

[sjsrey]

If my memory is correct, I think there are issues with the listing on pypi for packages, and my guess is that is why we had rst and md in some cases?

[weikang9009]

Based on the latest Python Packaging User Guide, it seems that we can set the parameterlong_description_content_type to be 'text/markdown' in setup() to use the content of README.md for the package long_description:

from setuptools import setup

# read the contents of your README file
from os import path
this_directory = path.abspath(path.dirname(__file__))
with open(path.join(this_directory, 'README.md'), encoding='utf-8') as f:
    long_description = f.read()

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

[darribas]

Closed as addressed in #26