Automate generation of reference docs with doxygen and breathe (#598)
* Make 'any' the default markup role for Sphinx docs
* Automate generation of reference docs with doxygen and breathe
* Improve reference docs coverage
diff --git a/docs/Doxyfile b/docs/Doxyfile
new file mode 100644
index 0000000..4dc8bf0
--- /dev/null
+++ b/docs/Doxyfile
@@ -0,0 +1,19 @@
+PROJECT_NAME = pybind11
+INPUT = ../include/pybind11/
+
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_XML = YES
+XML_OUTPUT = .build/doxygenxml
+XML_PROGRAMLISTING = YES
+
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+EXPAND_AS_DEFINED = PYBIND11_RUNTIME_EXCEPTION
+
+ALIASES = "rst=\verbatim embed:rst"
+ALIASES += "endrst=\endverbatim"
+
+QUIET = YES
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = NO
diff --git a/docs/advanced/cast/chrono.rst b/docs/advanced/cast/chrono.rst
index 6d4a5ee..8c6b3d7 100644
--- a/docs/advanced/cast/chrono.rst
+++ b/docs/advanced/cast/chrono.rst
@@ -4,8 +4,8 @@
When including the additional header file :file:`pybind11/chrono.h` conversions
from C++11 chrono datatypes to python datetime objects are automatically enabled.
This header also enables conversions of python floats (often from sources such
-as `time.monotonic()`, `time.perf_counter()` and `time.process_time()`) into
-durations.
+as ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``)
+into durations.
An overview of clocks in C++11
------------------------------
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 8788885..7c97a0f 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -14,7 +14,7 @@
bindings for functions that return a non-trivial type. Just by looking at the
type information, it is not clear whether Python should take charge of the
returned value and eventually free its resources, or if this is handled on the
-C++ side. For this reason, pybind11 provides a several `return value policy`
+C++ side. 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`.
@@ -24,11 +24,11 @@
.. code-block:: cpp
- /* Function declaration */
+ /* Function declaration */
Data *get_data() { return _data; /* (pointer to a static data structure) */ }
...
- /* Binding code */
+ /* Binding code */
m.def("get_data", &get_data); // <-- KABOOM, will cause crash when called from Python
What's going on here? When ``get_data()`` is called from Python, the return
@@ -44,7 +44,7 @@
In the above example, the policy :enum:`return_value_policy::reference` should have
been specified so that the global data instance is only *referenced* without any
-implied transfer of ownership, i.e.:
+implied transfer of ownership, i.e.:
.. code-block:: cpp
@@ -158,9 +158,9 @@
Additional call policies
========================
-In addition to the above return value policies, further `call policies` can be
-specified to indicate dependencies between parameters. In general, call policies
-are required when the C++ object is any kind of container and another object is being
+In addition to the above return value policies, further *call policies* can be
+specified to indicate dependencies between parameters. In general, call policies
+are required when the C++ object is any kind of container and another object is being
added to the container.
There is currently just
diff --git a/docs/advanced/pycpp/object.rst b/docs/advanced/pycpp/object.rst
index 8e737cc..ae58876 100644
--- a/docs/advanced/pycpp/object.rst
+++ b/docs/advanced/pycpp/object.rst
@@ -33,6 +33,8 @@
When conversion fails, both directions throw the exception :class:`cast_error`.
+.. _calling_python_functions:
+
Calling Python functions
========================
diff --git a/docs/classes.rst b/docs/classes.rst
index 0bddfe2..2c1ff2a 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -38,7 +38,7 @@
return m.ptr();
}
-:class:`class_` creates bindings for a C++ `class` or `struct`-style data
+:class:`class_` creates bindings for a C++ *class* or *struct*-style data
structure. :func:`init` is a convenience function that takes the types of a
constructor's parameters as template arguments and wraps the corresponding
constructor (see the :ref:`custom_constructors` section for details). An
diff --git a/docs/conf.py b/docs/conf.py
index c8f9644..82dfe26 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,6 +16,7 @@
import sys
import os
import shlex
+import subprocess
# 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
@@ -30,7 +31,11 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = ['breathe']
+
+breathe_projects = {'pybind11': '.build/doxygenxml/'}
+breathe_default_project = 'pybind11'
+breathe_domain_by_extension = {'h': 'cpp'}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']
@@ -79,7 +84,7 @@
# The reST default role (used for this markup: `text`) to use for all
# documents.
-#default_role = None
+default_role = 'any'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
@@ -306,3 +311,22 @@
primary_domain = 'cpp'
highlight_language = 'cpp'
+
+
+def generate_doxygen_xml(app):
+ build_dir = '.build'
+ if not os.path.exists(build_dir):
+ os.mkdir(build_dir)
+
+ try:
+ subprocess.call(['doxygen', '--version'])
+ retcode = subprocess.call(['doxygen'])
+ if retcode < 0:
+ sys.stderr.write("doxygen error code: {}\n".format(-retcode))
+ except OSError as e:
+ sys.stderr.write("doxygen execution failed: {}\n".format(e))
+
+
+def setup(app):
+ """Add hook for building doxygen xml when needed"""
+ app.connect("builder-inited", generate_doxygen_xml)
diff --git a/docs/environment.yml b/docs/environment.yml
new file mode 100644
index 0000000..5a3332b
--- /dev/null
+++ b/docs/environment.yml
@@ -0,0 +1,9 @@
+name: rtd
+channels:
+- dean0x7d
+- defaults
+dependencies:
+- doxygen
+- pip
+- pip:
+ - https://github.com/michaeljones/breathe/archive/master.zip
diff --git a/docs/reference.rst b/docs/reference.rst
index 542259e..3d211f7 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -12,236 +12,69 @@
Macros
======
-.. function:: PYBIND11_PLUGIN(const char *name)
-
- This macro creates the entry point that will be invoked when the Python
- interpreter imports a plugin library. Please create a
- :class:`module` in the function body and return the pointer to its
- underlying Python object at the end.
-
- .. code-block:: cpp
-
- PYBIND11_PLUGIN(example) {
- pybind11::module m("example", "pybind11 example plugin");
- /// Set up bindings here
- return m.ptr();
- }
+.. doxygendefine:: PYBIND11_PLUGIN
.. _core_types:
Convenience classes for arbitrary Python types
==============================================
+Common member functions
+-----------------------
+
+.. doxygenclass:: object_api
+ :members:
+
Without reference counting
--------------------------
-.. class:: handle
-
- The :class:`handle` class is a thin wrapper around an arbitrary Python
- object (i.e. a ``PyObject *`` in Python's C API). It does not perform any
- automatic reference counting and merely provides a basic C++ interface to
- various Python API functions.
-
-.. seealso::
-
- The :class:`object` class inherits from :class:`handle` and adds automatic
- reference counting features.
-
-.. function:: handle::handle()
-
- The default constructor creates a handle with a ``nullptr``-valued pointer.
-
-.. function:: handle::handle(const handle&)
-
- Copy constructor
-
-.. function:: handle::handle(PyObject *)
-
- Creates a :class:`handle` from the given raw Python object pointer.
-
-.. function:: PyObject * handle::ptr() const
-
- Return the ``PyObject *`` underlying a :class:`handle`.
-
-.. function:: const handle& handle::inc_ref() const
-
- Manually increase the reference count of the Python object. Usually, it is
- preferable to use the :class:`object` class which derives from
- :class:`handle` and calls this function automatically. Returns a reference
- to itself.
-
-.. function:: const handle& handle::dec_ref() const
-
- Manually decrease the reference count of the Python object. Usually, it is
- preferable to use the :class:`object` class which derives from
- :class:`handle` and calls this function automatically. Returns a reference
- to itself.
-
-.. function:: void handle::ref_count() const
-
- Return the object's current reference count
-
-.. function:: handle handle::get_type() const
-
- Return a handle to the Python type object underlying the instance
-
-.. function detail::accessor handle::operator[](handle key) const
-
- Return an internal functor to invoke the object's sequence protocol.
- Casting the returned ``detail::accessor`` instance to a :class:`handle` or
- :class:`object` subclass causes a corresponding call to ``__getitem__``.
- Assigning a :class:`handle` or :class:`object` subclass causes a call to
- ``__setitem__``.
-
-.. function detail::accessor handle::operator[](const char *key) const
-
- See the above function (the only difference is that they key is provided as
- a string literal).
-
-.. function detail::accessor handle::attr(handle key) const
-
- Return an internal functor to access the object's attributes.
- Casting the returned ``detail::accessor`` instance to a :class:`handle` or
- :class:`object` subclass causes a corresponding call to ``__getattr``.
- Assigning a :class:`handle` or :class:`object` subclass causes a call to
- ``__setattr``.
-
-.. function detail::accessor handle::attr(const char *key) const
-
- See the above function (the only difference is that they key is provided as
- a string literal).
-
-.. function operator handle::bool() const
-
- Return ``true`` when the :class:`handle` wraps a valid Python object.
-
-.. function str handle::str() const
-
- Return a string representation of the object. This is analogous to
- the ``str()`` function in Python.
-
-.. function:: template <typename T> T handle::cast() const
-
- Attempt to cast the Python object into the given C++ type. A
- :class:`cast_error` will be throw upon failure.
-
-.. function:: template <typename ... Args> object handle::call(Args&&... args) const
-
- Assuming the Python object is a function or implements the ``__call__``
- protocol, ``call()`` invokes the underlying function, passing an arbitrary
- set of parameters. The result is returned as a :class:`object` and may need
- to be converted back into a Python object using :func:`handle::cast`.
-
- When some of the arguments cannot be converted to Python objects, the
- function will throw a :class:`cast_error` exception. When the Python
- function call fails, a :class:`error_already_set` exception is thrown.
+.. doxygenclass:: handle
+ :members:
With reference counting
-----------------------
-.. class:: object : public handle
+.. doxygenclass:: object
+ :members:
- Like :class:`handle`, the object class is a thin wrapper around an
- arbitrary Python object (i.e. a ``PyObject *`` in Python's C API). In
- contrast to :class:`handle`, it optionally increases the object's reference
- count upon construction, and it *always* decreases the reference count when
- the :class:`object` instance goes out of scope and is destructed. When
- using :class:`object` instances consistently, it is much easier to get
- reference counting right at the first attempt.
+.. doxygenfunction:: reinterpret_borrow
-.. function:: object::object(const object &o)
-
- Copy constructor; always increases the reference count
-
-.. function:: object::object(const handle &h, bool borrowed)
-
- Creates a :class:`object` from the given :class:`handle`. The reference
- count is only increased if the ``borrowed`` parameter is set to ``true``.
-
-.. function:: object::object(PyObject *ptr, bool borrowed)
-
- Creates a :class:`object` from the given raw Python object pointer. The
- reference count is only increased if the ``borrowed`` parameter is set to
- ``true``.
-
-.. function:: object::object(object &&other)
-
- Move constructor; steals the object from ``other`` and preserves its
- reference count.
-
-.. function:: handle object::release()
-
- Resets the internal pointer to ``nullptr`` without without decreasing the
- object's reference count. The function returns a raw handle to the original
- Python object.
-
-.. function:: object::~object()
-
- Destructor, which automatically calls :func:`handle::dec_ref()`.
+.. doxygenfunction:: reinterpret_steal
Convenience classes for specific Python types
=============================================
+.. doxygenclass:: module
+ :members:
-.. class:: module : public object
-
-.. function:: module::module(const char *name, const char *doc = nullptr)
-
- Create a new top-level Python module with the given name and docstring
-
-.. function:: module module::def_submodule(const char *name, const char *doc = nullptr)
-
- Create and return a new Python submodule with the given name and docstring.
- This also works recursively, i.e.
-
- .. code-block:: cpp
-
- pybind11::module m("example", "pybind11 example plugin");
- pybind11::module m2 = m.def_submodule("sub", "A submodule of 'example'");
- pybind11::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
-
-.. cpp:function:: template <typename Func, typename ... Extra> module& module::def(const char *name, Func && f, Extra && ... extra)
-
- Create Python binding for a new function within the module scope. ``Func``
- can be a plain C++ function, a function pointer, or a lambda function. For
- details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
+.. doxygengroup:: pytypes
+ :members:
.. _extras:
-Passing extra arguments to the def function
-===========================================
+Passing extra arguments to ``def`` or ``class_``
+================================================
-.. class:: arg
+.. doxygengroup:: annotations
+ :members:
-.. function:: arg::arg(const char *name)
+Python build-in functions
+=========================
-.. function:: template <typename T> arg_v arg::operator=(T &&value)
+.. doxygengroup:: python_builtins
+ :members:
-.. class:: arg_v : public arg
+Exceptions
+==========
- Represents a named argument with a default value
+.. doxygenclass:: error_already_set
+ :members:
-.. class:: sibling
+.. doxygenclass:: builtin_exception
+ :members:
- Used to specify a handle to an existing sibling function; used internally
- to implement function overloading in :func:`module::def` and
- :func:`class_::def`.
-.. function:: sibling::sibling(handle handle)
+Literals
+========
-.. class doc
-
- This is class is internally used by pybind11.
-
-.. function:: doc::doc(const char *value)
-
- Create a new docstring with the specified value
-
-.. class name
-
- This is class is internally used by pybind11.
-
-.. function:: name::name(const char *value)
-
- Used to specify the function name
-
+.. doxygennamespace:: literals