Skip to content

Commit

Permalink
doc: improve west's repo-tool.rst
Browse files Browse the repository at this point in the history
Various improvements to the west repo-tool.rst page and pages that
link to it:

Rename the page title to "Basics", since it documents, well the
basics, including built-in commands like "help" an "config" that are
not directly related to multiple repositories.

The "multi-repo" term was invented before we started using
"workspace". Drop it from the text and rework things using words like
"workspace", "basics", or "built-ins" instead, which read better.

We've been using west for a long enough time that justifying its
existence prominently at the start of this page is no longer
necessary; move that to the "dustbin of history" page (why.rst).

Try harder to clarify exactly what a "project" is, along with other
workspace related clarifications.

Improve the documentation for the west init and west update commands,
and create :ref: targets for linking directly to them for convenience
elsewhere in the docs.

Slim down the usages for other built-in commands, so we don't have to
keep those up to date as carefully each release. This is about to be
important for west 0.9, which is going to change the detailed
semantics for the "[PROJECT ...]" part of each command synopsis in a
way that will be inconvenient to duplicate for each of these.

Move the "Topologies supported" content lower down. Try to help the
reading flow by letting people get familiar with a workspace and what
you can do with it using the Zephyr GSG workspace that they probably
already have before overwhelming them with other possibilities and
choices.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
  • Loading branch information
mbolivar-nordic authored and carlescufi committed Jan 7, 2021
1 parent 476e9e8 commit 7097e17
Show file tree
Hide file tree
Showing 4 changed files with 270 additions and 206 deletions.
2 changes: 1 addition & 1 deletion doc/guides/west/config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ commands are documented in the pages for those commands.
* - ``update.fetch``
- String, one of ``"smart"`` (the default behavior starting in v0.6.1) or
``"always"`` (the previous behavior). If set to ``"smart"``, the
:ref:`west update <west-multi-repo-cmds>` command will skip fetching
:ref:`west-update` command will skip fetching
from project remotes when those projects' revisions in the manifest file
are SHAs or tags which are already available locally. The ``"always"``
behavior is to unconditionally fetch from the remote.
Expand Down
2 changes: 1 addition & 1 deletion doc/guides/west/release-notes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ v0.6.1

The user-visible features in this point release are:

- The `west update <west-multi-repo-cmds>` command has a new ``--fetch``
- The :ref:`west-update` command has a new ``--fetch``
command line flag and ``update.fetch`` :ref:`configuration option
<west-config>`. The default value, "smart", skips fetching SHAs and tags
which are available locally.
Expand Down
Loading

0 comments on commit 7097e17

Please sign in to comment.