From 0b9acc4009afdda427b5f151a67d500216707dc1 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sun, 18 Oct 2020 14:31:28 -0400 Subject: [PATCH] fix: chapters in PDF again (#2606) * fix: chapters in PDF again * fix: sections in README --- README.rst | 93 +++++++++++++++++++++++++------------------------- docs/conf.py | 29 +++++++++++++++- docs/index.rst | 2 +- 3 files changed, 76 insertions(+), 48 deletions(-) diff --git a/README.rst b/README.rst index 7ee5884db..3f8349ef8 100644 --- a/README.rst +++ b/README.rst @@ -1,8 +1,7 @@ .. 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 `_. + 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 `_ - 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 `_ + 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 ------------------- diff --git a/docs/conf.py b/docs/conf.py index 7c3039842..66db310e4 100644 --- a/docs/conf.py +++ b/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) diff --git a/docs/index.rst b/docs/index.rst index 2d96936ec..4e2e8ca3a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ Intro ===== -.. include:: ../README.rst +.. include:: readme.rst .. only:: not latex