docs: Use README.rst in docs as home page (#2500)

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

README.md

@@ -1,145 +0,0 @@
-![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png)
-
-# pybind11 — Seamless operability between C++11 and Python
-
-[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=master)](http://pybind11.readthedocs.org/en/master/?badge=master)
-[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=stable)](http://pybind11.readthedocs.org/en/stable/?badge=stable)
-[![Gitter chat](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/pybind/Lobby)
-[![CI](https://github.com/pybind/pybind11/workflows/CI/badge.svg)](https://github.com/pybind/pybind11/actions)
-[![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](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

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 <http://www.boost.org/doc/libs/1_58_0/libs/python/doc/>`_
+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 <http://pybind11.readthedocs.org/en/master>`_.
+A PDF version of the manual is available
+`here <https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf>`_.
+And the source code is always available at
+`github.com/pybind/pybind11 <https://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 <http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf>`_
+   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 <https://github.com/pybind/pybind11/issues/276>`_)
+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 <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_
+for information on building and contributing to pybind11.
+
+License
+~~~~~~~
+
+pybind11 is provided under a BSD-style license that can be found in the
+`LICENSE <https://github.com/pybind/pybind11/blob/master/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

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',

docs/index.rst

@@ -1,11 +1,4 @@
-.. only: not latex
+.. include:: ../README.rst
-
-    .. image:: pybind11-logo.png
-
-pybind11 --- Seamless operability between C++11 and Python
-==========================================================
-
-Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_.
 
 .. only: not latex
 
@@ -14,7 +7,6 @@ Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/
 .. toctree::
    :maxdepth: 1
 
-   intro
    changelog
    upgrade
 

docs/intro.rst

@@ -1,93 +0,0 @@
-.. image:: pybind11-logo.png
-
-About this project
-==================
-**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.
-
-.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html
-
-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.x, or PyPy2.7 >= 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 <https://github.com/pybind/pybind11/issues/276>`_ )

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
-long_description = file: README.md
+long_description = file: README.rst
-long_description_content_type = text/markdown
+long_description_content_type = text/x-rst
 description = Seamless operability between C++11 and Python
 author = Wenzel Jakob
 author_email = "wenzel.jakob@epfl.ch"

tests/extra_python_package/test_files.py

@@ -80,7 +80,7 @@ sdist_files = {
     "setup.py",
     "LICENSE",
     "MANIFEST.in",
-    "README.md",
+    "README.rst",
     "PKG-INFO",
 }