docs: fix pdf build, simpler start page (#2736)

README.rst

@@ -11,6 +11,8 @@
 • `Scikit-build example <https://github.com/pybind/scikit_build_example>`_
 • `CMake example <https://github.com/pybind/cmake_example>`_
 
+.. start
+
 .. warning::
 
    Combining older versions of pybind11 (< 2.6.0) with Python 3.9.0 will
@@ -24,6 +26,7 @@
    the latest version of pybind11 (2.6.0 or newer), which includes a temporary
    workaround specifically when Python 3.9.0 is detected at runtime.
 
+
 **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
@@ -171,7 +174,7 @@ to the terms and conditions of this license.
 
 .. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest
    :target: http://pybind11.readthedocs.org/en/latest
-.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue
+.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue.svg
    :target: http://pybind11.readthedocs.org/en/stable
 .. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
    :target: https://gitter.im/pybind/Lobby
@@ -179,11 +182,11 @@ to the terms and conditions of this license.
    :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
-.. |PyPI package| image:: https://img.shields.io/pypi/v/pybind11
+.. |PyPI package| image:: https://img.shields.io/pypi/v/pybind11.svg
    :target: https://pypi.org/project/pybind11/
-.. |Conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pybind11
+.. |Conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pybind11.svg
    :target: https://github.com/conda-forge/pybind11-feedstock
 .. |Repology| image:: https://repology.org/badge/latest-versions/python:pybind11.svg
    :target: https://repology.org/project/python:pybind11/versions
-.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pybind11
+.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pybind11.svg
    :target: https://pypi.org/project/pybind11/

docs/changelog.rst

@@ -11,29 +11,31 @@ v2.6.2 (TBA, not yet released)
 ------------------------------
 
 
-* Fixed segfault in multithreaded environments when using ``scoped_ostream_redirect``.
-  `#2675 <https://github.com/pybind/pybind11/pull/2675>`_
-
-* CMake: mixing local and installed pybind11's would prioritize the installed one over the local one (regression in 2.6.0).
-  `#2716 <https://github.com/pybind/pybind11/pull/2716>`_
+* Allow thread termination to be avoided during shutdown for CPython 3.7+ via
+  ``.disarm``.
+  `#2657 <https://github.com/pybind/pybind11/pull/2657>`_
 
-* Fix bug where the constructor of `object` subclasses would not throw on being passed a Python object of the wrong type.
+* Fix bug where the constructor of ``object`` subclasses would not throw on
+  being passed a Python object of the wrong type.
   `#2701 <https://github.com/pybind/pybind11/pull/2701>`_
 
-* Fixed assertion error related to unhandled (later overwritten) exception in CPython 3.8 and 3.9 debug builds.
+* Fixed segfault in multithreaded environments when using
+  ``scoped_ostream_redirect``.
+  `#2675 <https://github.com/pybind/pybind11/pull/2675>`_
+
+* Fixed assertion error related to unhandled (later overwritten) exception in
+  CPython 3.8 and 3.9 debug builds.
   `#2685 <https://github.com/pybind/pybind11/pull/2685>`_
 
 * Fix ``py::gil_scoped_acquire`` assert with CPython 3.9 debug build.
   `#2683 <https://github.com/pybind/pybind11/pull/2683>`_
 
-* Fixes segfaults in multithreaded environments when using ``scoped_ostream_redirect``.
-  `#2675 <https://github.com/pybind/pybind11/pull/2675>`_
-
-* Fix issue with FindPython2/FindPython3 not working with ``pybind11::embed``.
+* CMake: Fix issue with FindPython2/FindPython3 not working with ``pybind11::embed``.
   `#2662 <https://github.com/pybind/pybind11/pull/2662>`_
 
-* Allow thread termination to be avoided during shutdown for CPython 3.7+ via ``.disarm``.
-  `#2657 <https://github.com/pybind/pybind11/pull/2657>`_
+* CMake: mixing local and installed pybind11's would prioritize the installed
+  one over the local one (regression in 2.6.0).
+  `#2716 <https://github.com/pybind/pybind11/pull/2716>`_
 
 
 

docs/conf.py

@@ -239,6 +239,8 @@ htmlhelp_basename = "pybind11doc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = "pdflatex"
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -353,8 +355,11 @@ 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":
+        # Remove badges and stuff from start
+        contents = contents[contents.find(r".. start") :]
+
+        # Filter out section titles for index.rst for LaTeX
         contents = re.sub(r"^(.*)\n[-~]{3,}$", r"**\1**", contents, flags=re.MULTILINE)
 
     with open(DIR / "readme.rst", "w") as f:

docs/requirements.txt

-breathe==4.20.0
+breathe==4.25.1
 commonmark==0.9.1
-recommonmark==0.6.0
-sphinx==3.2.1
+recommonmark==0.7.1
+sphinx==3.3.1
 sphinx_rtd_theme==0.5.0
-sphinxcontrib-moderncmakedomain==3.13
+sphinxcontrib-moderncmakedomain==3.17
 sphinxcontrib-svg2pdfconverter==1.1.0