Skip to content

P
pybind11
Commit ec0d38ef by Dean Moldovan
Options

Update the docs to reflect the new test structure 

Test compilation instructions for Windows were changed to use the
`cmake --build` command line invocation which should be easier than
manually setting up using the CMake GUI and Visual Studio.
parent 18319d55
Showing with 41 additions and 43 deletions
docs/advanced.rst
......@@ -102,7 +102,7 @@ C++ side, or to perform other types of customization.
.. seealso::
The file :file:`example/example-operator-overloading.cpp` contains a
The file :file:`tests/test_operator_overloading.cpp` contains a
complete example that demonstrates how to work with overloaded operators in
more detail.
......@@ -203,14 +203,14 @@ The following interactive session shows how to call them from Python.
is passed as an argument to another C++ function exposed in Python. In this
case, there is no overhead. Pybind11 will extract the underlying C++
function pointer from the wrapped function to sidestep a potential C++ ->
Python -> C++ roundtrip. This is demonstrated in Example 5.
Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`.
.. note::
This functionality is very useful when generating bindings for callbacks in
C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).
The file :file:`example/example-callbacks.cpp` contains a complete example
The file :file:`tests/test_callbacks.cpp` contains a complete example
that demonstrates how to work with callbacks and anonymous functions in
more detail.
......@@ -354,7 +354,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
.. seealso::
The file :file:`example/example-virtual-functions.cpp` contains a complete
The file :file:`tests/test_virtual_functions.cpp` contains a complete
example that demonstrates how to override virtual functions using pybind11
in more detail.
......@@ -472,7 +472,7 @@ can now create a python class that inherits from ``Dog``:
.. seealso::
See the file :file:`example-virtual-functions.cpp` for complete examples
See the file :file:`tests/test_virtual_functions.cpp` for complete examples
using both the duplication and templated trampoline approaches.
.. _macro_notes:
......@@ -556,7 +556,7 @@ out of the box with just the core :file:`pybind11/pybind11.h` header.
.. seealso::
The file :file:`example/example-python-types.cpp` contains a complete
The file :file:`tests/test_python_types.cpp` contains a complete
example that demonstrates how to pass STL data types in more detail.
Binding sequence data types, iterators, the slicing protocol, etc.
......@@ -566,7 +566,7 @@ Please refer to the supplemental example for details.
.. seealso::
The file :file:`example/example-sequences-and-iterators.cpp` contains a
The file :file:`tests/test_sequences_and_iterators.cpp` contains a
complete example that shows how to bind a sequence data type, including
length queries (``__len__``), iterators (``__iter__``), the slicing
protocol and other kinds of useful operations.
......@@ -690,7 +690,7 @@ container:
.. seealso::
The file :file:`example/example-keep-alive.cpp` contains a complete example
The file :file:`tests/test_keep_alive.cpp` contains a complete example
that demonstrates using :class:`keep_alive` in more detail.
Implicit type conversions
......@@ -892,7 +892,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
.. seealso::
The file :file:`example/example-smart-ptr.cpp` contains a complete example
The file :file:`tests/test_smart_ptr.cpp` contains a complete example
that demonstrates how to work with custom reference-counting holder types
in more detail.
......@@ -1005,7 +1005,7 @@ a first shot at handling the exception).
Inside the translator, ``std::rethrow_exception`` should be used within
a try block to re-throw the exception. A catch clause can then use
``PyErr_SetString`` to set a Python exception as demonstrated
in :file:`example-custom-exceptions.cpp``.
in :file:`tests/test_exceptions.cpp`.
This example also demonstrates how to create custom exception types
with ``py::exception``.
......@@ -1143,7 +1143,7 @@ Please take a look at the :ref:`macro_notes` before using this feature.
.. seealso::
The file :file:`example/example-opaque-types.cpp` contains a complete
The file :file:`tests/test_opaque_types.cpp` contains a complete
example that demonstrates how to create and expose opaque types using
pybind11 in more detail.
......@@ -1198,7 +1198,7 @@ with NumPy and SciPy.
.. seealso::
The file :file:`example/eigen.cpp` contains a complete example that
The file :file:`tests/test_eigen.cpp` contains a complete example that
shows how to pass Eigen sparse and dense data types in more detail.
Buffer protocol
......@@ -1326,7 +1326,7 @@ limitations), refer to the section on :ref:`eigen`.
.. seealso::
The file :file:`example/example-buffers.cpp` contains a complete example
The file :file:`tests/test_buffers.cpp` contains a complete example
that demonstrates using the buffer protocol with pybind11 in more detail.
.. [#f2] http://docs.python.org/3/c-api/buffer.html
......@@ -1493,7 +1493,7 @@ simply using ``vectorize``).
.. seealso::
The file :file:`example/example-numpy-vectorize.cpp` contains a complete
The file :file:`tests/test_numpy_vectorize.cpp` contains a complete
example that demonstrates using :func:`vectorize` in more detail.
Functions taking Python objects as arguments
......@@ -1557,9 +1557,9 @@ with other parameters.
.. seealso::
The file :file:`example/example-python-types.cpp` contains a complete
The file :file:`tests/test_python_types.cpp` contains a complete
example that demonstrates passing native Python types in more detail. The
file :file:`example/example-arg-keywords-and-defaults.cpp` discusses usage
file :file:`tests/test_kwargs_and_defaults.cpp` discusses usage
of ``args`` and ``kwargs``.
Default arguments revisited
......@@ -1633,7 +1633,7 @@ Such functions can also be created using pybind11:
/// Binding code
m.def("generic", &generic);
(See ``example/example-arg-keywords-and-defaults.cpp``). The class ``py::args``
(See ``tests/test_kwargs_and_defaults.cpp``). The class ``py::args``
derives from ``py::list`` and ``py::kwargs`` derives from ``py::dict`` Note
that the ``kwargs`` argument is invalid if no keyword arguments were actually
provided. Please refer to the other examples for details on how to iterate
......@@ -1783,7 +1783,7 @@ memory corruption and/or segmentation faults.
.. seealso::
The file :file:`example/example-pickling.cpp` contains a complete example
The file :file:`tests/test_pickling.cpp` contains a complete example
that demonstrates how to pickle and unpickle types using pybind11 in more
detail.
......
docs/basics.rst
......@@ -5,7 +5,7 @@ First steps
This sections demonstrates the basic features of pybind11. Before getting
started, make sure that development environment is set up to compile the
included set of examples, which also double as test cases.
included set of test cases.
Compiling the test cases
......@@ -22,44 +22,42 @@ After installing the prerequisites, run
.. code-block:: bash
cmake .
make -j 4
mkdir build
cd build
cmake ..
make pytest -j 4
followed by
.. code-block:: bash
make test
The last line will both compile and run the tests.
Windows
-------
On Windows, use the `CMake GUI`_ to create a Visual Studio project. Note that
only the 2015 release and newer versions are supported since pybind11 relies on
various C++11 language features that break older versions of Visual Studio.
After running CMake, open the created :file:`pybind11.sln` file and perform a
release build, which will will produce a file named
:file:`Release\\example.pyd`. Copy this file to the :file:`example` directory
and run :file:`example\\run_test.py` using the targeted Python version.
On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies
on various C++11 language features that break older versions of Visual Studio.
.. _`CMake GUI`: https://cmake.org/runningcmake
To compile and run the tests:
.. Note::
.. code-block:: batch
mkdir build
cd build
cmake ..
cmake --build . --config Release --target pytest
When all tests fail, make sure that
This will create a Visual Studio project, compile and run the target, all from the
command line.
1. The Python binary and the testcases are compiled for the same processor
type and bitness (i.e. either **i386** or **x86_64**)
.. Note::
2. The Python binary used to run :file:`example\\run_test.py` matches the
Python version specified in the CMake GUI. This is controlled via
the ``PYTHON_EXECUTABLE`` ``PYTHON_INCLUDE_DIR``, and
``PYTHON_LIBRARY`` variables.
If all tests fail, make sure that the Python binary and the testcases are compiled
for the same processor type and bitness (i.e. either **i386** or **x86_64**). You
can specify **x86_64** as the target architecture for the generated Visual Studio
project using ``cmake -A x64 ..``.
.. seealso::
Advanced users who are already familiar with Boost.Python may want to skip
the tutorial and look at the test cases in the :file:`example` directory,
the tutorial and look at the test cases in the :file:`tests` directory,
which exercise all features of pybind11.
Creating bindings for a simple function
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment