From 247047bf21bc58ee339fc0d8f00631180abb8b8a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 22 Jul 2019 11:00:22 -0600 Subject: [PATCH] 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 --- doc/guides/west/build-flash-debug.rst | 25 +++++++++++++++++-------- doc/guides/west/index.rst | 3 +-- doc/guides/west/west-apis.rst | 19 ------------------- doc/guides/west/west-not-found.rst | 1 - 4 files changed, 18 insertions(+), 30 deletions(-) diff --git a/doc/guides/west/build-flash-debug.rst b/doc/guides/west/build-flash-debug.rst index 655a364467a..c3cd2d2390e 100644 --- a/doc/guides/west/build-flash-debug.rst +++ b/doc/guides/west/build-flash-debug.rst @@ -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 +******* -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`. +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:`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 **************** diff --git a/doc/guides/west/index.rst b/doc/guides/west/index.rst index 00dd88773b3..48a38510315 100644 --- a/doc/guides/west/index.rst +++ b/doc/guides/west/index.rst @@ -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 diff --git a/doc/guides/west/west-apis.rst b/doc/guides/west/west-apis.rst index 1b2ed5a4876..24113ee2b5e 100644 --- a/doc/guides/west/west-apis.rst +++ b/doc/guides/west/west-apis.rst @@ -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 diff --git a/doc/guides/west/west-not-found.rst b/doc/guides/west/west-not-found.rst index a584f6bf191..d54c3b4fe2d 100644 --- a/doc/guides/west/west-not-found.rst +++ b/doc/guides/west/west-not-found.rst @@ -7,7 +7,6 @@ .. _west-apis-log: .. _west-apis-manifest: .. _west-apis-util: -.. _west-apis-zext: West APIs #########