fix: chapters in PDF again (#2606)

* fix: chapters in PDF again

* fix: sections in README

README.rst

 .. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png
    :alt: pybind11 logo
 
-pybind11 — Seamless operability between C++11 and Python
-========================================================
+**pybind11 — Seamless operability between C++11 and Python**
 
 |Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |CI| |Build status|
 
@@ -53,27 +52,29 @@ A PDF version of the manual is available
 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
+- 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
 -------
@@ -81,43 +82,43 @@ Goodies
 In addition to the core functionality, pybind11 provides some extra
 goodies:
 
--  Python 2.7, 3.5+, and PyPy/PyPy3 7.3 are supported with an
-   implementation-agnostic interface.
+- Python 2.7, 3.5+, and PyPy/PyPy3 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.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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**.
+- 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.
+- 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.
+- With little extra effort, C++ types can be pickled and unpickled
+  similar to regular Python objects.
 
 Supported compilers
 -------------------

docs/conf.py

@@ -17,6 +17,10 @@ import sys
 import os
 import shlex
 import subprocess
+from pathlib import Path
+import re
+
+DIR = Path(__file__).parent.resolve()
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -345,6 +349,29 @@ def generate_doxygen_xml(app):
         sys.stderr.write("doxygen execution failed: {}\n".format(e))
 
 
+def prepare(app):
+    with open(DIR.parent / "README.rst") as f:
+        contents = f.read()
+
+    # Filter out section titles for index.rst for LaTeX
+    if app.builder.name == "latex":
+        contents = re.sub(r"^(.*)\n[-~]{3,}$", r"**\1**", contents, flags=re.MULTILINE)
+
+    with open(DIR / "readme.rst", "w") as f:
+        f.write(contents)
+
+
+def clean_up(app, exception):
+    (DIR / "readme.rst").unlink()
+
+
 def setup(app):
-    """Add hook for building doxygen xml when needed"""
+
+    # Add hook for building doxygen xml when needed
     app.connect("builder-inited", generate_doxygen_xml)
+
+    # Copy the readme in
+    app.connect("builder-inited", prepare)
+
+    # Clean up the generated readme
+    app.connect("build-finished", clean_up)

docs/index.rst

@@ -3,7 +3,7 @@
    Intro
    =====
 
-.. include:: ../README.rst
+.. include:: readme.rst
 
 .. only:: not latex