From efa2b20d69cd7daa57b41a559a71117b2c34a369 Mon Sep 17 00:00:00 2001
From: DWesl <22566757+DWesl@users.noreply.github.com>
Date: Thu, 22 Aug 2024 00:29:21 -0400
Subject: [PATCH] docs: clarify requirements for including pybind11 (#5326)

* DOC: Clarify requirements for including pybind11

Inherited from requirements for including Python.h

Closes #4999

* style: pre-commit fixes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 docs/basics.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/basics.rst b/docs/basics.rst
index e9b24c7fa..cd97c100e 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -78,6 +78,13 @@ For brevity, all code examples assume that the following two lines are present:
 
     namespace py = pybind11;
 
+.. note::
+
+    ``pybind11/pybind11.h`` includes ``Python.h``, as such it must be the first file
+    included in any source file or header for `the same reasons as Python.h`_.
+
+.. _`the same reasons as Python.h`: https://docs.python.org/3/extending/extending.html#a-simple-example
+
 Some features may require additional headers, but those will be specified as needed.
 
 .. _simple_example: