From 5be097071c83c935777bde117fa85cd1f64c690a Mon Sep 17 00:00:00 2001 From: Rebecca Turner <637275@gmail.com> Date: Sat, 17 Mar 2018 11:58:20 -0400 Subject: [PATCH 1/3] Migrated README to Markdown (PEP 566) 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) --- MANIFEST.in | 3 +++ README.md | 37 +++++++++++++++++++++++++++++++++++++ README.rst | 32 -------------------------------- setup.py | 9 ++++++++- 4 files changed, 48 insertions(+), 33 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/MANIFEST.in b/MANIFEST.in index a4fa0c0d..c066bbd4 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,6 @@ +# Include the README +include *.md + # Include the license file include LICENSE.txt diff --git a/README.md b/README.md new file mode 100644 index 00000000..3fb999a7 --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# 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 +Projects][distribution tutorial]. + +This projects does not aim to cover best practices for Python project +development as a whole. For example, it does not provide guidance or tool +recommendations for version control, documentation, or testing. + +[The source for this project is available here][src]. + +Most of the configuration for a Python project is done in the `setup.py` file, +an example of which is included in this project. You should edit this file +accordingly to adapt this sample project to your needs. + +---- + +This is the README file for the project. + +The file should use UTF-8 encoding and can be written using +[reStructuredText][rst] or [markdown][md use] with the appropriate [key set][md +use]. It will be used to generate the project webpage on PyPI and will be +displayed as the project homepage on common code-hosting services, and should be +written for that purpose. + +Typical contents for this file would include an overview of the project, basic +usage examples, etc. Generally, including the project changelog in here is not a +good idea, although a simple “What's New” section for the most recent version +may be appropriate. + +[packaging guide]: https://twitter.com/mcclure111/status/975031304742895616 +[distribution tutorial]: https://twitter.com/mcclure111/status/975031304742895616 +[src]: https://twitter.com/mcclure111/status/975031304742895616 +[rst]: https://twitter.com/mcclure111/status/975031304742895616 +[md]: https://tools.ietf.org/html/rfc7764#section-3.5 "CommonMark variant" +[md use]: https://packaging.python.org/specifications/core-metadata/#description-content-type-optional diff --git a/README.rst b/README.rst deleted file mode 100644 index d2f04a00..00000000 --- a/README.rst +++ /dev/null @@ -1,32 +0,0 @@ -A sample Python project -======================= - -A sample project that exists as an aid to the `Python Packaging User Guide -`_'s `Tutorial on Packaging and Distributing -Projects `_. - -This projects does not aim to cover best practices for Python project -development as a whole. For example, it does not provide guidance or tool -recommendations for version control, documentation, or testing. - -`The source for this project is available here -`_. - -Most of the configuration for a Python project is done in the ``setup.py`` -file, an example of which is included in this project. You should edit this -file accordingly to adapt this sample project to your needs. - ----- - -This is the README file for the project. - -The file should use UTF-8 encoding and be written using `reStructuredText -`_. It -will be used to generate the project webpage on PyPI and will be displayed as -the project homepage on common code-hosting services, and should be written for -that purpose. - -Typical contents for this file would include an overview of the project, basic -usage examples, etc. Generally, including the project changelog in here is not -a good idea, although a simple "What's New" section for the most recent version -may be appropriate. diff --git a/setup.py b/setup.py index 27227e0b..254ebd04 100644 --- a/setup.py +++ b/setup.py @@ -14,7 +14,7 @@ here = path.abspath(path.dirname(__file__)) # Get the long description from the README file -with open(path.join(here, 'README.rst'), encoding='utf-8') as f: +with open(path.join(here, 'README.md'), encoding='utf-8') as f: long_description = f.read() # Arguments marked as "Required" below must be included for upload to PyPI. @@ -57,6 +57,13 @@ # https://packaging.python.org/specifications/core-metadata/#description-optional long_description=long_description, # Optional + # Denotes that our long_description is in Markdown; valid values are + # text/plain, text/x-rst, and text/markdown + # + # 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 + # This should be a valid link to your project's main homepage. # # This field corresponds to the "Home-Page" metadata field: From 10bef87464422245a05a093cf44e73b2bf4d0248 Mon Sep 17 00:00:00 2001 From: Rebecca Turner <637275@gmail.com> Date: Tue, 20 Mar 2018 01:00:31 -0400 Subject: [PATCH 2/3] Clarified when content_type is optional 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. --- setup.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/setup.py b/setup.py index 254ebd04..d285c7eb 100644 --- a/setup.py +++ b/setup.py @@ -60,6 +60,11 @@ # 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 + # 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) + # # 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 From 79b599a8911ab89544f4115816868bc956aa17e9 Mon Sep 17 00:00:00 2001 From: Rebecca Turner <637275@gmail.com> Date: Tue, 20 Mar 2018 02:00:25 -0400 Subject: [PATCH 3/3] Typos and clarifications * 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` --- README.md | 4 ++-- setup.py | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3fb999a7..03c8eca1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # 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 +Guide][packaging guide]'s [Tutorial on Packaging and Distributing Projects][distribution tutorial]. -This projects does not aim to cover best practices for Python project +This project does not aim to cover best practices for Python project development as a whole. For example, it does not provide guidance or tool recommendations for version control, documentation, or testing. diff --git a/setup.py b/setup.py index d285c7eb..312248b7 100644 --- a/setup.py +++ b/setup.py @@ -60,14 +60,14 @@ # 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 - # 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) + # Optional if long_description is written in reStructuredText (rst) but + # required for 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) # # 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 + long_description_content_type='text/markdown', # Optional (see note above) # This should be a valid link to your project's main homepage. #