.. _gendata:

Generator Customization
=======================

Because robotpy-build's code generation is intended to be a semi-automated
process (except for simple C++ code), a rich set of per-{class/function/parameter}
configuration options can be specified in per-file YAML configurations.

Additionally, some headers are too complex for the autogenerator to
completely process, so when this occurs you must manually specify required
information in the YAML file.

Most files generated by robotpy-build are customizable.

.. note:: robotpy-build is designed for the RobotPy project and may contain
          defaults that aren't appropriate for all projects. If you find that
          you need more customization, file an issue on github and let's talk
          about it!

Location of customization file
------------------------------

In your ``pyproject.toml``, you can specify either a single YAML file with
customizations, or you can specify a directory that robotpy-build will search
for YAML files.

Single file:

.. code-block:: toml

   [tool.robotpy-build.wrappers."PACKAGENAME"]
   generation_data = "gen/data.yml"

Multiple files:

.. code-block:: toml

   [tool.robotpy-build.wrappers."PACKAGENAME"]
   generation_data = "gen"

When a directory is specified, pybind11 will search for YAML files in the
directory based on the header filename. In the above example, customization
data for ``header.h`` could be specified in ``gen/header.yml``.


Autogeneration
--------------

The default values for these YAML files can be generated via the robotpy-build
command line tool:

.. code-block:: sh

   robotpy-build create-gen --write

This can be a good way to get the boilerplate out of the way when you need to
provide customizations.

Reference
---------

The following strctures describe the dictionaries that are read from the YAML
file. The toplevel structure is :class:`.HooksDataYaml`.

.. automodule:: robotpy_build.hooks_datacfg
   :members:
   :undoc-members: