diff --git a/MANIFEST.in b/MANIFEST.in
index 9336b603..2e11abe0 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,4 @@
recursive-include pybind11/include/pybind11 *.h
recursive-include pybind11 *.py
include pybind11/share/cmake/pybind11/*.cmake
-include LICENSE README.md pyproject.toml setup.py setup.cfg
+include LICENSE README.rst pyproject.toml setup.py setup.cfg
diff --git a/README.md b/README.md
deleted file mode 100644
index 69a0fc90..00000000
--- a/README.md
+++ /dev/null
@@ -1,145 +0,0 @@
-
-
-# pybind11 — Seamless operability between C++11 and Python
-
-[](http://pybind11.readthedocs.org/en/master/?badge=master)
-[](http://pybind11.readthedocs.org/en/stable/?badge=stable)
-[](https://gitter.im/pybind/Lobby)
-[](https://github.com/pybind/pybind11/actions)
-[](https://ci.appveyor.com/project/wjakob/pybind11)
-
-**pybind11** is a lightweight header-only library that exposes C++ types in
-Python and vice versa, mainly to create Python bindings of existing C++ code.
-Its goals and syntax are similar to the excellent [Boost.Python][] library by
-David Abrahams: to minimize boilerplate code in traditional extension modules
-by inferring type information using compile-time introspection.
-
-The main issue with Boost.Python—and the reason for creating such a similar
-project—is Boost. Boost is an enormously large and complex suite of utility
-libraries that works with almost every C++ compiler in existence. This
-compatibility has its cost: arcane template tricks and workarounds are
-necessary to support the oldest and buggiest of compiler specimens. Now that
-C++11-compatible compilers are widely available, this heavy machinery has
-become an excessively large and unnecessary dependency.
-
-Think of this library as a tiny self-contained version of Boost.Python with
-everything stripped away that isn't relevant for binding generation. Without
-comments, the core header files only require ~4K lines of code and depend on
-Python (2.7 or 3.5+, or PyPy) and the C++ standard library. This compact
-implementation was possible thanks to some of the new C++11 language features
-(specifically: tuples, lambda functions and variadic templates). Since its
-creation, this library has grown beyond Boost.Python in many ways, leading to
-dramatically simpler binding code in many common situations.
-
-Tutorial and reference documentation is provided at
-[pybind11.readthedocs.org][]. A PDF version of the manual is available
-[here][docs-pdf].
-
-## Core features
-pybind11 can map the following core C++ features to Python:
-
-- Functions accepting and returning custom data structures per value, reference, or pointer
-- Instance methods and static methods
-- Overloaded functions
-- Instance attributes and static attributes
-- Arbitrary exception types
-- Enumerations
-- Callbacks
-- Iterators and ranges
-- Custom operators
-- Single and multiple inheritance
-- STL data structures
-- Smart pointers with reference counting like `std::shared_ptr`
-- Internal references with correct reference counting
-- C++ classes with virtual (and pure virtual) methods can be extended in Python
-
-## Goodies
-In addition to the core functionality, pybind11 provides some extra goodies:
-
-- Python 2.7, 3.5+, and PyPy (tested on 7.3) are supported with an implementation-agnostic
- interface.
-
-- It is possible to bind C++11 lambda functions with captured variables. The
- lambda capture data is stored inside the resulting Python function object.
-
-- pybind11 uses C++11 move constructors and move assignment operators whenever
- possible to efficiently transfer custom data types.
-
-- It's easy to expose the internal storage of custom data types through
- Pythons' buffer protocols. This is handy e.g. for fast conversion between
- C++ matrix classes like Eigen and NumPy without expensive copy operations.
-
-- pybind11 can automatically vectorize functions so that they are transparently
- applied to all entries of one or more NumPy array arguments.
-
-- Python's slice-based access and assignment operations can be supported with
- just a few lines of code.
-
-- Everything is contained in just a few header files; there is no need to link
- against any additional libraries.
-
-- Binaries are generally smaller by a factor of at least 2 compared to
- equivalent bindings generated by Boost.Python. A recent pybind11 conversion
- of PyRosetta, an enormous Boost.Python binding project,
- [reported][pyrosetta-report] a binary size reduction of **5.4x** and compile
- time reduction by **5.8x**.
-
-- Function signatures are precomputed at compile time (using `constexpr`),
- leading to smaller binaries.
-
-- With little extra effort, C++ types can be pickled and unpickled similar to
- regular Python objects.
-
-## Supported compilers
-
-1. Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer)
-2. GCC 4.8 or newer
-3. Microsoft Visual Studio 2015 Update 3 or newer
-4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11
- v2.0 and a [workaround][intel-15-workaround])
-5. Cygwin/GCC (tested on 2.5.1)
-6. NVCC (CUDA 11 tested)
-7. NVIDIA PGI (20.7 tested)
-
-## About
-
-This project was created by [Wenzel Jakob](http://rgl.epfl.ch/people/wjakob).
-Significant features and/or improvements to the code were contributed by
-Jonas Adler,
-Lori A. Burns,
-Sylvain Corlay,
-Trent Houliston,
-Axel Huebl,
-@hulucc,
-Sergey Lyskov
-Johan Mabille,
-Tomasz Miąsko,
-Dean Moldovan,
-Ben Pritchard,
-Jason Rhinelander,
-Boris Schäling,
-Pim Schellart,
-Henry Schreiner,
-Ivan Smirnov, and
-Patrick Stewart.
-
-### Contributing
-
-See the [contributing guide][] for information on building and contributing to
-pybind11.
-
-
-### License
-
-pybind11 is provided under a BSD-style license that can be found in the
-[`LICENSE`][] file. By using, distributing, or contributing to this project,
-you agree to the terms and conditions of this license.
-
-
-[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/master
-[docs-pdf]: https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf
-[Boost.Python]: http://www.boost.org/doc/libs/1_58_0/libs/python/doc/
-[pyrosetta-report]: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf
-[contributing guide]: https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md
-[`LICENSE`]: https://github.com/pybind/pybind11/blob/master/LICENSE
-[intel-15-workaround]: https://github.com/pybind/pybind11/issues/276
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..811167ff
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,158 @@
+.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png
+ :alt: pybind11 logo
+
+pybind11 — Seamless operability between C++11 and Python
+========================================================
+
+|Documentation Status| |image1| |Gitter chat| |CI| |Build status|
+
+**pybind11** is a lightweight header-only library that exposes C++ types
+in Python and vice versa, mainly to create Python bindings of existing
+C++ code. Its goals and syntax are similar to the excellent
+`Boost.Python `_
+library by David Abrahams: to minimize boilerplate code in traditional
+extension modules by inferring type information using compile-time
+introspection.
+
+The main issue with Boost.Python—and the reason for creating such a
+similar project—is Boost. Boost is an enormously large and complex suite
+of utility libraries that works with almost every C++ compiler in
+existence. This compatibility has its cost: arcane template tricks and
+workarounds are necessary to support the oldest and buggiest of compiler
+specimens. Now that C++11-compatible compilers are widely available,
+this heavy machinery has become an excessively large and unnecessary
+dependency.
+
+Think of this library as a tiny self-contained version of Boost.Python
+with everything stripped away that isn’t relevant for binding
+generation. Without comments, the core header files only require ~4K
+lines of code and depend on Python (2.7 or 3.5+, or PyPy) and the C++
+standard library. This compact implementation was possible thanks to
+some of the new C++11 language features (specifically: tuples, lambda
+functions and variadic templates). Since its creation, this library has
+grown beyond Boost.Python in many ways, leading to dramatically simpler
+binding code in many common situations.
+
+Tutorial and reference documentation is provided at
+`pybind11.readthedocs.org `_.
+A PDF version of the manual is available
+`here `_.
+And the source code is always available at
+`github.com/pybind/pybind11 `_.
+
+Core features
+-------------
+
+pybind11 can map the following core C++ features to Python:
+
+- Functions accepting and returning custom data structures per value,
+ reference, or pointer
+- Instance methods and static methods
+- Overloaded functions
+- Instance attributes and static attributes
+- Arbitrary exception types
+- Enumerations
+- Callbacks
+- Iterators and ranges
+- Custom operators
+- Single and multiple inheritance
+- STL data structures
+- Smart pointers with reference counting like ``std::shared_ptr``
+- Internal references with correct reference counting
+- C++ classes with virtual (and pure virtual) methods can be extended
+ in Python
+
+Goodies
+-------
+
+In addition to the core functionality, pybind11 provides some extra
+goodies:
+
+- Python 2.7, 3.5+, and PyPy (tested on 7.3) are supported with an
+ implementation-agnostic interface.
+
+- It is possible to bind C++11 lambda functions with captured
+ variables. The lambda capture data is stored inside the resulting
+ Python function object.
+
+- pybind11 uses C++11 move constructors and move assignment operators
+ whenever possible to efficiently transfer custom data types.
+
+- It’s easy to expose the internal storage of custom data types through
+ Pythons’ buffer protocols. This is handy e.g. for fast conversion
+ between C++ matrix classes like Eigen and NumPy without expensive
+ copy operations.
+
+- pybind11 can automatically vectorize functions so that they are
+ transparently applied to all entries of one or more NumPy array
+ arguments.
+
+- Python’s slice-based access and assignment operations can be
+ supported with just a few lines of code.
+
+- Everything is contained in just a few header files; there is no need
+ to link against any additional libraries.
+
+- Binaries are generally smaller by a factor of at least 2 compared to
+ equivalent bindings generated by Boost.Python. A recent pybind11
+ conversion of PyRosetta, an enormous Boost.Python binding project,
+ `reported `_
+ a binary size reduction of **5.4x** and compile time reduction by
+ **5.8x**.
+
+- Function signatures are precomputed at compile time (using
+ ``constexpr``), leading to smaller binaries.
+
+- With little extra effort, C++ types can be pickled and unpickled
+ similar to regular Python objects.
+
+Supported compilers
+-------------------
+
+1. Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 or
+ newer)
+2. GCC 4.8 or newer
+3. Microsoft Visual Studio 2015 Update 3 or newer
+4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with
+ pybind11 v2.0 and a
+ `workaround `_)
+5. Cygwin/GCC (tested on 2.5.1)
+6. NVCC (CUDA 11 tested)
+7. NVIDIA PGI (20.7 tested)
+
+About
+-----
+
+This project was created by `Wenzel
+Jakob `_. Significant features and/or
+improvements to the code were contributed by Jonas Adler, Lori A. Burns,
+Sylvain Corlay, Trent Houliston, Axel Huebl, @hulucc, Sergey Lyskov
+Johan Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason
+Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan
+Smirnov, and Patrick Stewart.
+
+Contributing
+~~~~~~~~~~~~
+
+See the `contributing
+guide `_
+for information on building and contributing to pybind11.
+
+License
+~~~~~~~
+
+pybind11 is provided under a BSD-style license that can be found in the
+`LICENSE `_
+file. By using, distributing, or contributing to this project, you agree
+to the terms and conditions of this license.
+
+.. |Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge/?version=master
+ :target: http://pybind11.readthedocs.org/en/master/?badge=master
+.. |image1| image:: https://readthedocs.org/projects/pybind11/badge/?version=stable
+ :target: http://pybind11.readthedocs.org/en/stable/?badge=stable
+.. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
+ :target: https://gitter.im/pybind/Lobby
+.. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg
+ :target: https://github.com/pybind/pybind11/actions
+.. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true
+ :target: https://ci.appveyor.com/project/wjakob/pybind11
diff --git a/docs/conf.py b/docs/conf.py
index b3242767..d3f73613 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,7 +31,7 @@ import subprocess
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['breathe']
+extensions = ['breathe', 'sphinx.ext.imgconverter']
breathe_projects = {'pybind11': '.build/doxygenxml/'}
breathe_default_project = 'pybind11'
@@ -242,7 +242,10 @@ latex_elements = {
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
-'preamble': r'\DeclareUnicodeCharacter{00A0}{}',
+'preamble': r'''
+\DeclareUnicodeCharacter{00A0}{}
+\DeclareUnicodeCharacter{2194}{<->}
+''',
# Latex figure (float) alignment
#'figure_align': 'htbp',
diff --git a/docs/index.rst b/docs/index.rst
index 69ce4d69..699e6920 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,11 +1,4 @@
-.. only: not latex
-
- .. image:: pybind11-logo.png
-
-pybind11 --- Seamless operability between C++11 and Python
-==========================================================
-
-Source code available at `github.com/pybind/pybind11 `_.
+.. include:: ../README.rst
.. only: not latex
@@ -14,7 +7,6 @@ Source code available at `github.com/pybind/pybind11 = 5.7) and the C++ standard library. This
-compact implementation was possible thanks to some of the new C++11 language
-features (specifically: tuples, lambda functions and variadic templates). Since
-its creation, this library has grown beyond Boost.Python in many ways, leading
-to dramatically simpler binding code in many common situations.
-
-Core features
-*************
-The following core C++ features can be mapped to Python
-
-- Functions accepting and returning custom data structures per value, reference, or pointer
-- Instance methods and static methods
-- Overloaded functions
-- Instance attributes and static attributes
-- Arbitrary exception types
-- Enumerations
-- Callbacks
-- Iterators and ranges
-- Custom operators
-- Single and multiple inheritance
-- STL data structures
-- Smart pointers with reference counting like ``std::shared_ptr``
-- Internal references with correct reference counting
-- C++ classes with virtual (and pure virtual) methods can be extended in Python
-
-Goodies
-*******
-In addition to the core functionality, pybind11 provides some extra goodies:
-
-- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an
- implementation-agnostic interface.
-
-- It is possible to bind C++11 lambda functions with captured variables. The
- lambda capture data is stored inside the resulting Python function object.
-
-- pybind11 uses C++11 move constructors and move assignment operators whenever
- possible to efficiently transfer custom data types.
-
-- It's easy to expose the internal storage of custom data types through
- Pythons' buffer protocols. This is handy e.g. for fast conversion between
- C++ matrix classes like Eigen and NumPy without expensive copy operations.
-
-- pybind11 can automatically vectorize functions so that they are transparently
- applied to all entries of one or more NumPy array arguments.
-
-- Python's slice-based access and assignment operations can be supported with
- just a few lines of code.
-
-- Everything is contained in just a few header files; there is no need to link
- against any additional libraries.
-
-- Binaries are generally smaller by a factor of at least 2 compared to
- equivalent bindings generated by Boost.Python. A recent pybind11 conversion
- of `PyRosetta`_, an enormous Boost.Python binding project, reported a binary
- size reduction of **5.4x** and compile time reduction by **5.8x**.
-
-- Function signatures are precomputed at compile time (using ``constexpr``),
- leading to smaller binaries.
-
-- With little extra effort, C++ types can be pickled and unpickled similar to
- regular Python objects.
-
-.. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf
-
-Supported compilers
-*******************
-
-1. Clang/LLVM (any non-ancient version with C++11 support)
-2. GCC 4.8 or newer
-3. Microsoft Visual Studio 2015 or newer
-4. Intel C++ compiler v17 or newer (v16 with pybind11 v2.0 and v15 with pybind11 v2.0 and a `workaround `_ )
diff --git a/setup.cfg b/setup.cfg
index ca0d59a4..0e03ddce 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
[metadata]
-long_description = file: README.md
-long_description_content_type = text/markdown
+long_description = file: README.rst
+long_description_content_type = text/x-rst
description = Seamless operability between C++11 and Python
author = Wenzel Jakob
author_email = "wenzel.jakob@epfl.ch"
diff --git a/tests/extra_python_package/test_files.py b/tests/extra_python_package/test_files.py
index ac8ca1f9..94df1e7f 100644
--- a/tests/extra_python_package/test_files.py
+++ b/tests/extra_python_package/test_files.py
@@ -80,7 +80,7 @@ sdist_files = {
"setup.py",
"LICENSE",
"MANIFEST.in",
- "README.md",
+ "README.rst",
"PKG-INFO",
}