From 40d87e5a129974402783547d1a7c061e43358a13 Mon Sep 17 00:00:00 2001
From: "John T. Wodder II" <git@varonathe.org>
Date: Sun, 16 Sep 2018 00:37:39 +0000
Subject: [PATCH 1/2] Added a section on checking RST markup

---
 .../guides/making-a-pypi-friendly-readme.rst  | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst
index 3399f9ff2..cd0bf13d6 100644
--- a/source/guides/making-a-pypi-friendly-readme.rst
+++ b/source/guides/making-a-pypi-friendly-readme.rst
@@ -81,3 +81,23 @@ and identifies the markup as GitHub-flavored Markdown:
        long_description=long_description,
        long_description_content_type='text/markdown'
    )
+
+
+Validating reStructuredText markup
+----------------------------------
+
+If your README is written in reStructuredText, any invalid markup will prevent
+it from rendering, causing PyPI to instead just show the README's raw source.
+You can check your README for markup errors before uploading as follows:
+
+1. Install `readme_renderer <https://github.com/pypa/readme_renderer>`_, the
+   README rendering library used by PyPI::
+
+        pip install readme_renderer
+
+2. Run::
+
+        python setup.py check -r -s
+
+    This command will report any problems rendering your README.  If nothing is
+    reported, your markup renders fine.

From 4574c512891d5e4e033a3094ed64d80ace0978d2 Mon Sep 17 00:00:00 2001
From: "John T. Wodder II" <git@varonathe.org>
Date: Mon, 17 Sep 2018 23:16:22 +0000
Subject: [PATCH 2/2] Recommend `twine check` instead

---
 .../guides/making-a-pypi-friendly-readme.rst   | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst
index cd0bf13d6..a894755c1 100644
--- a/source/guides/making-a-pypi-friendly-readme.rst
+++ b/source/guides/making-a-pypi-friendly-readme.rst
@@ -90,14 +90,18 @@ If your README is written in reStructuredText, any invalid markup will prevent
 it from rendering, causing PyPI to instead just show the README's raw source.
 You can check your README for markup errors before uploading as follows:
 
-1. Install `readme_renderer <https://github.com/pypa/readme_renderer>`_, the
-   README rendering library used by PyPI::
+1. Install the latest version of `twine <https://github.com/pypa/twine>`_;
+   version 1.12.0 or higher is required::
 
-        pip install readme_renderer
+        pip install --upgrade twine
 
-2. Run::
+2. Build the sdist and wheel for your project as described under
+   :ref:`Packaging Your Project`.
 
-        python setup.py check -r -s
+3. Run ``twine check`` on the sdist and wheel::
 
-    This command will report any problems rendering your README.  If nothing is
-    reported, your markup renders fine.
+        twine check dist/*
+
+   This command will report any problems rendering your README.  If your markup
+   renders fine, the command will output ``Checking distribution FILENAME:
+   Passed``.