Migrated README to Markdown (PEP 566) #66
Conversation
Migrated `README.rst` to `README.md` and updated `setup.py` to match; this is in line with PEP 566 and the new long_description_content_type arg in setuptools. Also updated `MANIFEST.in` to include the new `README.md`. See: * [Relevant section in PEP 566](https://www.python.org/dev/peps/pep-0566/#description-content-type-optional) * [The CommonMark specification](http://spec.commonmark.org) * [The Description-Content-Type field documentation in the Python packaging documentation](https://packaging.python.org/specifications/core-metadata/#description-content-type-optional)
setup.py
Outdated
| # | ||
| # This field corresponds to the "Description-Content-Type" metadata field: | ||
| # https://packaging.python.org/specifications/core-metadata/#description-content-type-optional | ||
| long_description_content_type='text/markdown', # Optional |
There was a problem hiding this comment.
Might want to add a note here that while this field is technically optional, it's required if you want a Markdown long_description.
|
Added a comment to clarify:
|
setup.py
Outdated
| # plain-text or Markdown; if unspecified, "applications should attempt to | ||
| # render [the long_description] as text/x-rst; charset=UTF-8 and fall back | ||
| # to text/plain if it is not valid rst" (see link below) | ||
| # |
There was a problem hiding this comment.
I think this is in the wrong place, it should be below long_description_content_type=....
There was a problem hiding this comment.
Yeah, noticed just after pushing. Should be updated now.
Added a comment clarifying that `long_description_content_type` in `setup()` is only optional if the `long_description` is written in RST and a quote from relevant documentation.
README.md
Outdated
| # A sample Python project | ||
|
|
||
| A sample project that exists as an aid to the [Python Packaging User | ||
| Guide][packaging guide]’s [Tutorial on Packaging and Distributing |
There was a problem hiding this comment.
Could you replace the ’ character with ' here?
README.md
Outdated
| Guide][packaging guide]’s [Tutorial on Packaging and Distributing | ||
| Projects][distribution tutorial]. | ||
|
|
||
| This projects does not aim to cover best practices for Python project |
There was a problem hiding this comment.
There's a typo here that's not your fault, should be "this project".
setup.py
Outdated
| # Denotes that our long_description is in Markdown; valid values are | ||
| # text/plain, text/x-rst, and text/markdown | ||
| # | ||
| # Optional if long_description is written in rst but required for |
There was a problem hiding this comment.
Could you change rst here to reStructuredText? Since newcomers might not know what "rst" stands for.
setup.py
Outdated
| # | ||
| # This field corresponds to the "Description-Content-Type" metadata field: | ||
| # https://packaging.python.org/specifications/core-metadata/#description-content-type-optional | ||
| long_description_content_type='text/markdown', # Optional |
There was a problem hiding this comment.
Maybe change # Optional here to # Optional (see note above)?
* Changed true quotes to ASCII quotes in `README.md` * Fixed a typo (`This projects` instead of `This project`) in `README.md` * Changed `rst` to `reStructuredText (rst)` in `setup.py` for people who might not be familiar with the format * Added small note to `# Optional` comment on the `long_description_content_type` arg in `setup.py:L70`
|
OK, fixed. |
There was a problem hiding this comment.
Great! I'm going to hold off on merging this until pypi/warehouse#869 is closed.
|
Can we get this merged now that pypi/warehouse#869 is closed? |
|
Thanks @9999years! |
Migrated
README.rsttoREADME.mdand updatedsetup.pyto match;this is in line with PEP 566 and the new
long_description_content_typearg in setuptools.
Also updated
MANIFEST.into include the newREADME.mdwithinclude *.mdas suggested bycheck-manifest— is that the right way to do that?See also:
packaging documentation