doc: document devicetree/pinctrl.h macros

Add a new section in the API reference for the newly added
devicetree/pinctrl.h macros.

Amend macros.bnf in the guide to reflect the new generated macros for
getting at pinctrl information by name.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>