diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index c5c672baae..6f359c2986 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1593,4 +1593,143 @@
+
+ Using a Development Python Shell
+
+
+ Similar to working within a development shell as described in
+ the previous section, you can also spawn and work within an
+ interactive Python development shell.
+ When debugging certain commands or even when just editing packages,
+ devpyshell can be a useful tool.
+ When you invoke devpyshell, all tasks up to and
+ including
+ do_patch
+ are run for the specified target.
+ Then, a new terminal is opened and you are placed in
+ ${S},
+ the source directory.
+ In the new terminal, all the OpenEmbedded build-related environment variables are
+ still defined so you can use commands such as configure and
+ make.
+ Additionally, key Python objects and code are available in the same
+ way they are to BitBake tasks, in particular, the data store 'd'.
+ So, commands such as the following are useful when exploring the data
+ store and running functions:
+
+ pydevshell> d.getVar("STAGING_DIR", True)
+ '/media/build1/poky/build/tmp/sysroots'
+ pydevshell> d.getVar("STAGING_DIR", False)
+ '${TMPDIR}/sysroots'
+ pydevshell> d.setVar("FOO", "bar")
+ pydevshell> d.getVar("FOO", True)
+ 'bar'
+ pydevshell> d.delVar("FOO")
+ pydevshell> d.getVar("FOO", True)
+ pydevshell> bb.build.exec_func("do_unpack", d)
+ pydevshell>
+
+ The commands execute just as if the OpenEmbedded build system were executing them.
+ Consequently, working this way can be helpful when debugging a build or preparing
+ software to be used with the OpenEmbedded build system.
+
+
+
+ Following is an example that uses devpyshell on a target named
+ matchbox-desktop:
+
+ $ bitbake matchbox-desktop -c devpyshell
+
+
+
+
+ This command spawns a terminal and places you in an interactive
+ Python interpreter within the OpenEmbedded build environment.
+ The OE_TERMINAL
+ variable controls what type of shell is opened.
+
+
+
+ For spawned terminals, the following occurs:
+
+ The PATH variable includes the
+ cross-toolchain.
+ The pkgconfig variables find the correct
+ .pc files.
+ The configure command finds the
+ Yocto Project site files as well as any other necessary files.
+
+
+
+
+ Within this environment, you can run configure or compile
+ commands as if they were being run by
+ the OpenEmbedded build system itself.
+ As noted earlier, the working directory also automatically changes to the
+ Source Directory (S).
+
+
+
+ To manually run a specific task using devpyshell,
+ run the corresponding run.* script in
+ the
+ ${WORKDIR}/temp
+ directory (e.g.,
+ run.do_configure.pid).
+ If a task's script does not exist, which would be the case if the task was
+ skipped by way of the sstate cache, you can create the task by first running
+ it outside of the devshell:
+
+ $ bitbake -c task
+
+ Notes
+
+ Execution of a task's run.*
+ script and BitBake's execution of a task are identical.
+ In other words, running the script re-runs the task
+ just as it would be run using the
+ bitbake -c command.
+
+ Any run.* file that does not
+ have a .pid extension is a
+ symbolic link (symlink) to the most recent version of that
+ file.
+
+
+
+
+
+
+ Remember, that the devpyshell is a mechanism that allows
+ you to get into the BitBake task execution environment
+ through an interactive Python interpreter.
+ And as such, all commands must be called just as BitBake would call them.
+ That means you need to provide the appropriate options for
+ cross-compilation and so forth as applicable.
+
+
+
+ When you are finished using devpyshell, exit the shell
+ or close the terminal window.
+
+
+ Notes
+
+
+ It is worth remembering that when using devpyshell
+ you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc
+ instead of just using gcc.
+ The same applies to other applications such as binutils,
+ libtool and so forth.
+ BitBake sets up environment variables such as CC
+ to assist applications, such as make to find the correct tools.
+
+
+ It is also worth noting that devpyshell still works over
+ X11 forwarding and similar situations.
+
+
+
+
+
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index 0ad3632538..f05d0f8eb7 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -684,6 +684,22 @@
+
+ do_devpyshell
+
+
+ Starts a shell in which an interactive Python interpreter allows
+ you to interact with the BitBake build environment.
+ From within this shell, you can directly examine and set
+ bits from the data store and execute functions as if within
+ the BitBake environment.
+ See the
+ "Using a Development Python Shell"
+ section in the Yocto Project Development Manual for more
+ information about using devpyshell.
+
+
+