doc: west: 0.7.0 documentation

Reflect changes in the APIs made since 0.6.0. These will also need to
be added to the release notes.

Some automatic directives weren't generating the desired output, so
either do it by hand or let new 0.7.0 docstrings supply the information.

Try to better group the content into sections.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/guides/west/index.rst

@@ -27,7 +27,7 @@ You can run ``west --help`` (or ``west -h`` for short) to get top-level help
 for available west commands, and ``west <command> -h`` for detailed help on
 each command.
 
-The following pages document west's ``v0.6.x`` releases, and provide additional
+The following pages document west's ``v0.7.x`` releases, and provide additional
 context about the tool.
 
 .. toctree::
@@ -45,7 +45,6 @@ context about the tool.
    zephyr-cmds.rst
    why.rst
    without-west.rst
-   planned.rst
    release-notes.rst
 
 For details on west's Python APIs, see :ref:`west-apis`.

doc/guides/west/manifest.rst

@@ -89,6 +89,7 @@ top-level ``manifest`` section with some subsections, like this:
      self:
        # configuration related to the manifest repository itself,
        # i.e. the repository containing west.yml (optional)
+     version: <schema-version> # optional
 
 In YAML terms, the manifest file contains a mapping, with a ``manifest``
 key. Any other keys and their contents are ignored (west v0.5 also required a
@@ -249,7 +250,7 @@ so far using ``defaults`` is:
          url: https://github.com/user/project-three
          revision: abcde413a111
 
-Finally, the ``self`` subsection can be used to control the behavior of the
+The ``self`` subsection can be used to control the behavior of the
 manifest repository itself. Its value is a map with the following keys:
 
 - ``path``: Optional. The path to clone the manifest repository into, relative
@@ -283,8 +284,27 @@ zephyr repository does contain extension commands, its ``self`` entry declares
 the location of the corresponding :file:`west-commands.yml` relative to the
 repository root.
 
+.. _west-manifest-schema-version:
+
+The ``version`` subsection can be used to mark the lowest version of the
+manifest file schema that can parse this file's data:
+
+.. code-block:: yaml
+
+   manifest:
+     version: 0.7
+     # marks that this manifest uses features available in west 0.7 and
+     # up, like manifest imports
+
 The pykwalify schema :file:`manifest-schema.yml` in the west source code
-repository is used to validate the manifest section.
+repository is used to validate the manifest section. The current manifest
+``version`` is 0.7, which corresponds to west version 0.7. This is the only
+value this field can currently take.
+
+If a later version of west, say version ``21.0``, includes changes to the
+manifest schema that cannot be parsed by west 0.7, then setting ``version:
+21.0`` will cause west to print an error when attempting to parse the manifest
+data.
 
 .. _west-manifest-import:
 

doc/guides/west/planned.rst

@@ -1,6 +1,84 @@
 West Release Notes
 ##################
 
+v0.7.0
+******
+
+The main user-visible feature in west 0.7 is the :ref:`west-manifest-import`
+feature. This allows users to load west manifest data from multiple different
+files, resolving the results into a single logical manifest.
+
+Additional user-visible changes:
+
+- The idea of a "west installation" has been renamed to "west workspace" in
+  this documentation and in the west API documentation. The new term seems to
+  be easier for most people to work with than the old one.
+- West manifests now support a :ref:`schema version
+  <west-manifest-schema-version>`.
+- The "west config" command can now be run outside of a workspace, e.g.
+  to run ``west config --global section.key value`` to set a configuration
+  option's value globally.
+- There is a new :ref:`west topdir <west-multi-repo-misc>` command, which
+  prints the root directory of the current west workspace.
+- The ``west -vv init`` command now prints the git operations being performed,
+  and their results.
+- The restriction that no project can be named "manifest" is now enforced; the
+  name "manifest" is reserved for the manifest repository, and is usable as
+  such in commands like ``west list manifest``, instead of ``west list
+  path-to-manifest-repository`` being the only way to say that
+- It's no longer an error if there is no project named "zephyr". This is
+  part of an effort to make west generally usable for non-Zephyr use cases.
+- Various bug fixes.
+
+The developer-visible changes to the :ref:`west-apis` are:
+
+- west.build and west.cmake: deprecated; this is Zephyr-specific functionality
+  and should never have been part of west. Since Zephyr v1.14 LTS relies on it,
+  it will continue to be included in the distribution, but will be removed
+  when that version of Zephyr is obsoleted.
+- west.commands:
+
+  - WestCommand.requires_installation: deprecated; use requires_workspace instead
+  - WestCommand.requires_workspace: new
+  - WestCommand.has_manifest: new
+  - WestCommand.manifest: this is now settable
+- west.configuration: callers can now identify the workspace directory
+  when reading and writing configuration files
+- west.log:
+
+  - msg(): new
+- west.manifest:
+
+  - The module now uses the standard logging module instead of west.log
+  - QUAL_REFS_WEST: new
+  - SCHEMA_VERSION: new
+  - Defaults: removed
+  - Manifest.as_dict(): new
+  - Manifest.as_frozen_yaml(): new
+  - Manifest.as_yaml(): new
+  - Manifest.from_file() and from_data(): these factory methods are more
+    flexible to use and less reliant on global state
+  - Manifest.validate(): new
+  - ManifestImportFailed: new
+  - ManifestProject: semi-deprecated and will likely be removed later.
+  - Project: the constructor now takes a topdir argument
+  - Project.format() and its callers are removed. Use f-strings instead.
+  - Project.name_and_path: new
+  - Project.remote_name: new
+  - Project.sha() now captures stderr
+  - Remote: removed
+
+West now requires Python 3.6 or later. Additionally, some features may rely on
+Python dictionaries being insertion-ordered; this is only an implementation
+detail in CPython 3.6, but is is part of the language specification as of
+Python 3.7.
+
+v0.6.3
+******
+
+This point release fixes an error in the behavior of the deprecated
+``west.cmake`` module.
+
 v0.6.2
 ******
 

doc/guides/west/release-notes.rst

@@ -262,6 +262,17 @@ Miscellaneous Commands
 West has a few more commands for managing the multi-repo, which are briefly
 discussed here. Run ``west <command> -h`` for detailed help.
 
+- ``west forall -c COMMAND [PROJECT ...]``: Runs the shell command ``COMMAND``
+  within the top-level repository directory of each of the specified projects
+  (default: all cloned projects). If ``COMMAND`` consists of more than one
+  word, it must be quoted to prevent it from being split up by the shell.
+
+  To run an arbitrary Git command in each project, use something like ``west
+  forall -c 'git <command> --options'``. Note that ``west forall`` can be used
+  to run any command, though, not just Git commands.
+
+- ``west help <command>``: this is equivalent to ``west <command> -h``.
+
 - ``west list [-f FORMAT] [PROJECT ...]``: Lists project information from the
   manifest file, such as URL, revision, path, etc. The printed information can
   be controlled using the ``-f`` option.
@@ -278,16 +289,7 @@ discussed here. Run ``west <command> -h`` for detailed help.
 - ``west status [PROJECT ...]``: Like ``west diff``, for
   running ``git status``.
 
-- ``west forall -c COMMAND [PROJECT ...]``: Runs the shell command ``COMMAND``
-  within the top-level repository directory of each of the specified projects
-  (default: all cloned projects). If ``COMMAND`` consists of more than one
-  word, it must be quoted to prevent it from being split up by the shell.
-
-  To run an arbitrary Git command in each project, use something like ``west
-  forall -c 'git <command> --options'``. Note that ``west forall`` can be used
-  to run any command, though, not just Git commands.
-
-- ``west help <command>``: this is equivalent to ``west <command> -h``.
+- ``west topdir``: Prints the top directory of the west workspace.
 
 .. _PyPI:
    https://pypi.org/project/west/