diff --git a/docs/devguide/index.asciidoc b/docs/devguide/index.asciidoc
index 213dc7cccaf..6cc701592f0 100644
--- a/docs/devguide/index.asciidoc
+++ b/docs/devguide/index.asciidoc
@@ -27,6 +27,8 @@ include::./fields-yml.asciidoc[]
 
 include::./event-conventions.asciidoc[]
 
+include::./python.asciidoc[]
+
 include::./newdashboards.asciidoc[]
 
 include::./new_protocol.asciidoc[]
diff --git a/docs/devguide/python.asciidoc b/docs/devguide/python.asciidoc
index 4f9902af205..3e21b4ae1af 100644
--- a/docs/devguide/python.asciidoc
+++ b/docs/devguide/python.asciidoc
@@ -1,5 +1,5 @@
 [[python-beats]]
-== Python in Beats
+=== Python in Beats
 
 Python is used for Beats development, it is the language used to implement
 system tests and some other tools. Python dependencies are managed by the use of
@@ -9,7 +9,7 @@ https://docs.python.org/3/library/venv.html[venv].
 Beats development requires Python >= {python}.
 
 [[installing-python]]
-=== Installing Python and venv
+==== Installing Python and venv
 
 Python uses to be installed in many operating systems. If it is not installed in
 your system you can follow the instructions available in https://www.python.org/downloads/
@@ -32,7 +32,7 @@ sudo apt-get install python3.7 python3.7-venv
 It is recommended to use Python >= {python}.
 
 [[python-virtual-environments]]
-=== Working with virtual environments
+==== Working with virtual environments
 
 All `make` and `mage` targets manage their own virtual environments in a transparent
 way, so for the most common operations required when contributing to beats,
@@ -65,7 +65,7 @@ To recreate a virtual environment, remove its directory. All virtual
 environments are also removed with `make clean`.
 
 [[python-older-versions]]
-=== Working with older versions
+==== Working with older versions
 
 Older versions of Beats were not compatible with Python 3, if you need to
 temporary work on one of these versions of Beats, and you don't want to remove