documentation improvements
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 1c6f6e0..b70c593 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -41,15 +41,18 @@
public:
Vector2(float x, float y) : x(x), y(y) { }
- std::string toString() const { return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; }
-
Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); }
Vector2 operator*(float value) const { return Vector2(x * value, y * value); }
Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; }
Vector2& operator*=(float v) { x *= v; y *= v; return *this; }
- friend Vector2 operator*(float f, const Vector2 &v) { return Vector2(f * v.x, f * v.y); }
+ friend Vector2 operator*(float f, const Vector2 &v) {
+ return Vector2(f * v.x, f * v.y);
+ }
+ std::string toString() const {
+ return "[" + std::to_string(x) + ", " + std::to_string(y) + "]";
+ }
private:
float x, y;
};
@@ -411,6 +414,8 @@
that can be passed to the :func:`module::def` and :func:`class_::def`
functions. The default policy is :enum:`return_value_policy::automatic`.
+.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+
+--------------------------------------------------+----------------------------------------------------------------------------+
| Return value policy | Description |
+==================================================+============================================================================+
@@ -746,6 +751,8 @@
special exception classes that will map to different types of Python
exceptions:
+.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+
+--------------------------------------+------------------------------+
| C++ exception type | Python exception type |
+======================================+==============================+
@@ -1034,8 +1041,9 @@
Available types include :class:`handle`, :class:`object`, :class:`bool_`,
:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`,
-:class:`list`, :class:`dict`, :class:`slice`, :class:`capsule`,
-:class:`function`, :class:`buffer`, :class:`array`, and :class:`array_t`.
+:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`,
+:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`,
+:class:`array`, and :class:`array_t`.
In this kind of mixed code, it is often necessary to convert arbitrary C++
types to Python, which can be done using :func:`cast`:
diff --git a/docs/basics.rst b/docs/basics.rst
index a2a6084..f81c103 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -222,59 +222,59 @@
an additional extension header to be included). To pass other data structures
as arguments and return values, refer to the section on binding :ref:`classes`.
-+----------------------------+--------------------------+-----------------------+
-| Data type | Description | Header file |
-+============================+==========================+=======================+
-| int8_t, uint8_t | 8-bit integers | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| int16_t, uint16_t | 16-bit integers | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| int32_t, uint32_t | 32-bit integers | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| int64_t, uint64_t | 64-bit integers | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| ssize_t, size_t | Platform-dependent size | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| float, double | Floating point types | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| bool | Two-state Boolean type | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| char | Character literal | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| wchar_t | Wide character literal | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| const char * | UTF-8 string literal | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| const wchar_t * | Wide string literal | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::string | STL dynamic UTF-8 string | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::wstring | STL dynamic wide string | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::pair<T1, T2> | Pair of two custom types | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::tuple<...> | Arbitrary tuple of types | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::reference_wrapper<...>| Reference type wrapper | pybind11/pybind11.h |
-+----------------------------+--------------------------+-----------------------+
-| std::complex<T> | Complex numbers | pybind11/complex.h |
-+----------------------------+--------------------------+-----------------------+
-| std::array<T, Size> | STL static array | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::vector<T> | STL dynamic array | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::list<T> | STL linked list | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::map<T1, T2> | STL ordered map | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::unordered_map<T1, T2> | STL unordered map | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::set<T> | STL ordered set | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::unordered_set<T> | STL unordered set | pybind11/stl.h |
-+----------------------------+--------------------------+-----------------------+
-| std::function<...> | STL polymorphic function | pybind11/functional.h |
-+----------------------------+--------------------------+-----------------------+
++---------------------------------+--------------------------+-------------------------------+
+| Data type | Description | Header file |
++=================================+==========================+===============================+
+| ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``char`` | Character literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` |
++---------------------------------+--------------------------+-------------------------------+
.. [#f1] In practice, implementation and binding code will generally be located
diff --git a/docs/benchmark.rst b/docs/benchmark.rst
index c31e290..3659197 100644
--- a/docs/benchmark.rst
+++ b/docs/benchmark.rst
@@ -65,7 +65,13 @@
modest **1.2x** speedup relative to Boost.Python, which required 116.35
seconds).
-.. image:: pybind11_vs_boost_python1.svg
+.. only:: not latex
+
+ .. image:: pybind11_vs_boost_python1.svg
+
+.. only:: latex
+
+ .. image:: pybind11_vs_boost_python1.png
Module size
-----------
@@ -79,5 +85,12 @@
included here, hence the comparison is slightly shifted in Boost.Python's
favor.
-.. image:: pybind11_vs_boost_python2.svg
+.. only:: not latex
+
+ .. image:: pybind11_vs_boost_python2.svg
+
+.. only:: latex
+
+ .. image:: pybind11_vs_boost_python2.png
+
diff --git a/docs/cmake.rst b/docs/cmake.rst
index ace2167..7236ea8 100644
--- a/docs/cmake.rst
+++ b/docs/cmake.rst
@@ -29,11 +29,13 @@
project(example)
# Add a CMake parameter for choosing a desired Python version
- set(EXAMPLE_PYTHON_VERSION "" CACHE STRING "Python version to use for compiling the example library")
-
+ set(EXAMPLE_PYTHON_VERSION "" CACHE STRING
+ "Python version to use for compiling the example library")
+
include(CheckCXXCompilerFlag)
- # Set a default build configuration if none is specified. 'MinSizeRel' produces the smallest binaries
+ # Set a default build configuration if none is specified.
+ # 'MinSizeRel' produces the smallest binaries
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
message(STATUS "Setting build type to 'MinSizeRel' as none was specified.")
set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE)
@@ -53,7 +55,8 @@
find_package(PythonLibs REQUIRED)
endif()
- # The above sometimes returns version numbers like "3.4.3+"; the "+" must be removed for the next lines to work
+ # The above sometimes returns version numbers like "3.4.3+";
+ # the "+" must be removed for the next lines to work
string(REPLACE "+" "" PYTHONLIBS_VERSION_STRING "+${PYTHONLIBS_VERSION_STRING}")
# Uncomment the following line if you will also require a matching Python interpreter
@@ -88,7 +91,8 @@
# Include path for Python header files
include_directories(${PYTHON_INCLUDE_DIR})
- # Include path for pybind11 header files -- this may need to be changed depending on your setup
+ # Include path for pybind11 header files -- this may need to be
+ # changed depending on your setup
include_directories(${PROJECT_SOURCE_DIR}/pybind11/include)
# Create the binding library
@@ -143,11 +147,13 @@
set_target_properties(example PROPERTIES MACOSX_RPATH ".")
set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup ")
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
- add_custom_command(TARGET example POST_BUILD COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so)
+ add_custom_command(TARGET example POST_BUILD
+ COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so)
endif()
else()
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG)
- add_custom_command(TARGET example POST_BUILD COMMAND strip ${PROJECT_BINARY_DIR}/example.so)
+ add_custom_command(TARGET example POST_BUILD
+ COMMAND strip ${PROJECT_BINARY_DIR}/example.so)
endif()
endif()
endif()
diff --git a/docs/conf.py b/docs/conf.py
index ca76e19..9d25838 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -233,7 +233,7 @@
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+'preamble': '\DeclareUnicodeCharacter{00A0}{}',
# Latex figure (float) alignment
#'figure_align': 'htbp',
@@ -249,7 +249,7 @@
# The name of an image file (relative to this directory) to place at the top of
# the title page.
-#latex_logo = None
+# latex_logo = 'pybind11-logo.png'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
diff --git a/docs/faq.rst b/docs/faq.rst
index 2556105..4badaf6 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -120,15 +120,16 @@
return m.ptr();
}
-The various ``init_ex`` functions are contained in separate files that can be
-compiled independently from another. Following this approach will
+The various ``init_ex`` functions should be contained in separate files that
+can be compiled independently from another. Following this approach will
-1. enable parallel builds (if desired).
+1. reduce memory requirements per compilation unit.
-2. allow for faster incremental builds (e.g. if a single class definiton is
- changed, only a subset of the binding code may need to be recompiled).
+2. enable parallel builds (if desired).
-3. reduce memory requirements.
+3. allow for faster incremental builds. For instance, when a single class
+ definiton is changed, only a subset of the binding code will generally need
+ to be recompiled.
How can I create smaller binaries?
==================================
@@ -142,9 +143,17 @@
names in the compiled extension library can be extremely long. For instance,
the included test suite contains the following symbol:
-.. code-block:: cpp
+.. only:: html
- __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
+ .. code-block:: none
+
+ __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
+
+.. only:: not html
+
+ .. code-block:: cpp
+
+ __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
which is the mangled form of the following function type:
@@ -152,12 +161,12 @@
pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28])
-The memory needed to store just the name of this function (196 bytes) is larger
-than the actual piece of code (111 bytes) it represents! On the other hand,
-it's silly to even give this function a name -- after all, it's just a tiny
-cog in a bigger piece of machinery that is not exposed to the outside world.
-So we'll generally only want to export symbols for those functions which are
-actually called from the outside.
+The memory needed to store just the mangled name of this function (196 bytes)
+is larger than the actual piece of code (111 bytes) it represents! On the other
+hand, it's silly to even give this function a name -- after all, it's just a
+tiny cog in a bigger piece of machinery that is not exposed to the outside
+world. So we'll generally only want to export symbols for those functions which
+are actually called from the outside.
This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
and Clang, which sets the default symbol visibility to *hidden*. It's best to
diff --git a/docs/index.rst b/docs/index.rst
index 56a9c0c..5115171 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,13 @@
-.. image:: pybind11-logo.png
+.. only: not latex
+
+ .. image:: pybind11-logo.png
pybind11 --- Seamless operability between C++11 and Python
==========================================================
-Contents:
+.. only: not latex
+
+ Contents:
.. toctree::
:maxdepth: 2
diff --git a/docs/pybind11_vs_boost_python1.png b/docs/pybind11_vs_boost_python1.png
new file mode 100644
index 0000000..833231f
--- /dev/null
+++ b/docs/pybind11_vs_boost_python1.png
Binary files differ
diff --git a/docs/pybind11_vs_boost_python2.png b/docs/pybind11_vs_boost_python2.png
new file mode 100644
index 0000000..9f17272
--- /dev/null
+++ b/docs/pybind11_vs_boost_python2.png
Binary files differ
