Skip to content
Permalink
Browse files

doc: move runner documentation out of west-apis.rst

Now that the runners package no longer depends on west, we can move
the documentation for it from the orphan west-apis.rst page to the
build-flash-debug.rst page that documents the west extension commands
which use that package.

(This is a more logical place for this information, but it was
previously not possible to put it there since we must be able to build
the documentation on a system without west installed, excepting
content in west-apis.rst. Removing the dependency means the runners
automodule directive can safely appear in build-flash-debug.rst.)

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
  • Loading branch information...
mbolivar authored and carlescufi committed Jul 22, 2019
1 parent 6846de6 commit 247047bf21bc58ee339fc0d8f00631180abb8b8a
@@ -463,13 +463,22 @@ determined by the imported subclasses of ``ZephyrBinaryRunner``.
individual runner implementations are in other submodules, such as
``runners.nrfjprog``, ``runners.openocd``, etc.

Hacking and APIs
****************
Hacking
*******

This section contains documentation the ``runners.core`` module used by the
flash and debug commands. This is the core abstraction used to implement
support for these features.

.. warning::

These APIs are provided for reference, but they are more "shared code" used
to implement multiple extension commands than a stable API.

Developers can add support for new ways to flash and debug Zephyr
programs by implementing additional runners. To get this support into
upstream Zephyr, the runner should be added into a new or existing
``runners`` module, and imported from :file:`runner/__init__.py`.
Developers can add support for new ways to flash and debug Zephyr programs by
implementing additional runners. To get this support into upstream Zephyr, the
runner should be added into a new or existing ``runners`` module, and imported
from :file:`runners/__init__.py`.

.. note::

@@ -480,8 +489,8 @@ upstream Zephyr, the runner should be added into a new or existing
changes break existing test cases, CI testing on upstream pull
requests will fail.

API Documentation for the ``runners.core`` module can be found in
:ref:`west-apis`.
.. automodule:: runners.core
:members:

Doing it By Hand
****************
@@ -46,8 +46,7 @@ context about the tool.
planned.rst
release-notes.rst

For details on west's Python APIs (including APIs provided by extensions in the
zephyr), see :ref:`west-apis`.
For details on west's Python APIs, see :ref:`west-apis`.

.. rubric:: Footnotes

@@ -72,24 +72,5 @@ west.util
.. automodule:: west.util
:members: west_dir, west_topdir, WestNotFound

.. _west-apis-zext:

Zephyr Extensions
*****************

This section contains documentation for APIs used by the extension commands
which are part of the Zephyr repository. In particular, it documents the
``runners.core`` module used by the :ref:`west-build-flash-debug`
commands. This is the core abstraction used to implement support for these
features.

.. warning::

These APIs are provided for reference, but they are more "shared code" used
to implement multiple extension commands than a stable API.

.. automodule:: runners.core
:members:

.. _west #38:
https://github.com/zephyrproject-rtos/west/issues/38
@@ -7,7 +7,6 @@
.. _west-apis-log:
.. _west-apis-manifest:
.. _west-apis-util:
.. _west-apis-zext:

West APIs
#########

0 comments on commit 247047b

Please sign in to comment.
You can’t perform that action at this time.