diff --git a/doc/sphinx/Pacemaker_Python_API/index.rst b/doc/sphinx/Pacemaker_Python_API/index.rst
index 4706341ecf..5c7f191a49 100644
--- a/doc/sphinx/Pacemaker_Python_API/index.rst
+++ b/doc/sphinx/Pacemaker_Python_API/index.rst
@@ -1,6 +1,11 @@
 Contents
 --------
 
+The APIs are documented here in submodules, but each submodule class is
+included at the top level, so code should import directly from the
+``pacemaker`` module. For example, use ``from pacemaker import BuildOptions``,
+not ``from pacemaker.buildoptions import BuildOptions``.
+
 .. toctree::
 
    api