Skip to content

Commit

Permalink
documentation improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@wjakob
wjakob committed Apr 28, 2016
1 parent 6ca6e82 commit f64feaf
Show file tree
Hide file tree
Showing 9 changed files with 125 additions and 85 deletions.
18 changes: 13 additions & 5 deletions docs/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,18 @@ in C++.
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;
};
Expand Down Expand Up @@ -411,6 +414,8 @@ For this reason, pybind11 provides a several `return value policy` annotations
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 |
+==================================================+============================================================================+
Expand Down Expand Up @@ -746,6 +751,8 @@ automatically converted into a Python ``Exception``. pybind11 defines multiple
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 |
+======================================+==============================+
Expand Down Expand Up @@ -1034,8 +1041,9 @@ For instance, the following statement iterates over a Python ``dict``:
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`:
Expand Down
106 changes: 53 additions & 53 deletions docs/basics.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,59 +222,59 @@ The following basic data types are supported out of the box (some may require
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
Expand Down
17 changes: 15 additions & 2 deletions docs/benchmark.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,13 @@ the largest largest file with 2048 classes and a total of 8192 methods -- a
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
-----------
Expand All @@ -79,5 +85,12 @@ that it stores many definitions in an external library, whose size was not
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


20 changes: 13 additions & 7 deletions docs/cmake.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,13 @@ subdirectory named :file:`pybind11`.
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)
Expand All @@ -53,7 +55,8 @@ subdirectory named :file:`pybind11`.
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
Expand Down Expand Up @@ -88,7 +91,8 @@ subdirectory named :file:`pybind11`.
# 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
Expand Down Expand Up @@ -143,11 +147,13 @@ subdirectory named :file:`pybind11`.
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()
4 changes: 2 additions & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',
'preamble': '\DeclareUnicodeCharacter{00A0}{}',

# Latex figure (float) alignment
#'figure_align': 'htbp',
Expand All @@ -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.
Expand Down
Loading

0 comments on commit f64feaf

Please sign in to comment.