Feature/unify readme

README.md

@@ -1,28 +1,64 @@
 PyYAML
 ======
 
+The next generation YAML parser and emitter for Python.
+
 A full-featured YAML processing framework for Python
 
+[![PyYAML CI](https://github.com/yaml/pyyaml/actions/workflows/ci.yaml/badge.svg)](https://github.com/yaml/pyyaml/actions/workflows/ci.yaml)
+[![PyPI version](https://badge.fury.io/py/PyYAML.svg)](https://badge.fury.io/py/PyYAML)
+
+YAML is a data serialization format designed for human readability
+and interaction with scripting languages.  PyYAML is a YAML parser
+and emitter for Python.
+
+PyYAML features a complete YAML 1.1 parser, Unicode support, pickle
+support, capable extension API, and sensible error messages.  PyYAML
+supports standard YAML tags and provides Python-specific tags that
+allow to represent an arbitrary Python object.
+
+PyYAML is applicable for a broad range of tasks from complex
+configuration files to object serialization and persistence.
+
 ## Installation
 
-To install, type `python setup.py install`.
+To install, type following:
+
+```shell
+# recommended
+pip install PyYAML
+# or
+python setup.py install
+```
 
 By default, the `setup.py` script checks whether LibYAML is installed and if
 so, builds and installs LibYAML bindings.
 To skip the check and force installation of LibYAML bindings, use the option
 `--with-libyaml`: `python setup.py --with-libyaml install`.
 To disable the check and skip building and installing LibYAML bindings, use
-`--without-libyaml`: `python setup.py --without-libyaml install`.
+`--without-libyaml`:
+
+```shell
+# recommended
+python -m pip install pyyaml --global-option=--without-libyaml
+# or
+python setup.py --without-libyaml install
+# Ref: https://pip.pypa.io/en/stable/cli/pip_install/#per-requirement-overrides
+```
 
 When LibYAML bindings are installed, you may use fast LibYAML-based parser and
 emitter as follows:
 
+```python
     >>> yaml.load(stream, Loader=yaml.CLoader)
     >>> yaml.dump(data, Dumper=yaml.CDumper)
+```
 
 If you don't trust the input YAML stream, you should use:
 
+```python
     >>> yaml.safe_load(stream)
+```
 
 ## Testing
 

setup.py

@@ -1,19 +1,13 @@
+import codecs
+
 
 NAME = 'PyYAML'
 VERSION = '6.0'
 DESCRIPTION = "YAML parser and emitter for Python"
-LONG_DESCRIPTION = """\
-YAML is a data serialization format designed for human readability
-and interaction with scripting languages.  PyYAML is a YAML parser
-and emitter for Python.
-
-PyYAML features a complete YAML 1.1 parser, Unicode support, pickle
-support, capable extension API, and sensible error messages.  PyYAML
-supports standard YAML tags and provides Python-specific tags that
-allow to represent an arbitrary Python object.
-
-PyYAML is applicable for a broad range of tasks from complex
-configuration files to object serialization and persistence."""
+
+with codecs.open('README.md', encoding='utf-8') as f:
+    LONG_DESCRIPTION = f.read()
+
 AUTHOR = "Kirill Simonov"
 AUTHOR_EMAIL = 'xi@resolvent.net'
 LICENSE = "MIT"
@@ -290,6 +284,7 @@ def run(self):
         version=VERSION,
         description=DESCRIPTION,
         long_description=LONG_DESCRIPTION,
+        long_description_content_type='text/markdown',
         author=AUTHOR,
         author_email=AUTHOR_EMAIL,
         license=LICENSE,