docs: Various refinements ahead of launch
This is a series of changes across the documentation to improve the
overall first-user experience. Key changes:
1. New "Express setup" section in the "Getting Started" page.
2. Rename and reorder the left-hand menu bar components
3. Fix various copyright dates
4. Add presubmit animated gif to the pw_presubmit docs
Change-Id: I22a75ace8c2be15a6e5890d6e1b3618a1d53eefa
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 7ff895c..551d804 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -1,4 +1,4 @@
-# Pigweed Code of Conduct
+# Code of Conduct
## Our Pledge
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db260a0..2670eed 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,16 +6,18 @@
ensure the changes make sense for upstream. We generally go through a design
phase before making large changes.
+Before participating in our community, please take a moment to review our [code
+of conduct](CODE_OF_CONDUCT.md). We expect everyone who interacts with the
+project to respect these guidelines.
+
Pigweed contribution overview:
1. One-time contributor setup:
- * Sign the [Contributor License
- Agreement](https://cla.developers.google.com/).
- * Install the [gerrit commit hook](CONTRIBUTING.md#gerrit-commit-hook) to
- automatically add a Change-ID to your CL.
+ * Sign the [Contributor License Agreement](https://cla.developers.google.com/).
+ * Install the [Gerrit commit hook](CONTRIBUTING.md#gerrit-commit-hook) to
+ automatically add a `Change-Id: ...` line to your commit
* Install the Pigweed presubmit check hook (`pw presubmit --install`).
(recommended)
- 2. Ensure all files include a correct [copyright+license
- header](CONTRIBUTING.md#source-code-headers).
+ 2. Ensure all files include a correct [copyright and license header](CONTRIBUTING.md#source-code-headers).
2. Upload the change with `git push origin HEAD:refs/for/master`.
3. Address any reviewer feedback by amending the commit (`git commit --amend`)
4. Submit change to CI builders to merge.
@@ -34,7 +36,7 @@
## Gerrit Commit Hook
-Gerrit requires all changes to have a Change-ID tag at the bottom of each CL.
+Gerrit requires all changes to have a `Change-Id` tag at the bottom of each CL.
You should set this up to be done automatically using the instructions below.
**Linux/macOS**<br/>
@@ -73,7 +75,7 @@
Apache header for C and C++ files:
```javascript
-// Copyright 2019 The Pigweed Authors
+// Copyright 2020 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
@@ -91,7 +93,7 @@
Apache header for Python and GN files:
```python
-# Copyright 2019 The Pigweed Authors
+# Copyright 2020 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
diff --git a/README.md b/README.md
index c099ecd..74e8fe8 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,10 @@
32-bit microcontrollers like the STMicroelectronics STM32L452 or the Nordic
nRF52832.
-Pigweed is in the early stages of development, and should be considered
-experimental. We’re continuing to evolve the platform and add new modules. We
+Pigweed is in the early stages of development, **and should be considered
+experimental**. We’re continuing to evolve the platform and add new modules. We
value developer feedback along the way.
-Pigweed is an open source project with a [code of conduct](CODE_OF_CONDUCT.md)
-that we expect everyone who interacts with the project to respect.
-
# Getting Started
If you'd like to get set up with Pigweed, please visit the
@@ -22,10 +19,10 @@
There are many modules in Pigweed, and this section only showcases a small
selection that happen to produce visual output. For more information about the
-different Pigweed module offerings, refer to "modules" section in the full
+different Pigweed module offerings, refer to "Module Guides" section in the full
documentation.
-## pw_watch
+## `pw_watch` - Build, flash, run, & test on save
In the web development space, file system watchers are prevalent. These watchers
trigger a web server reload on source change, making development much faster. In
@@ -35,30 +32,31 @@
the full dependency tree, only the exact tests affected by a file change are run
on saves.
-The demo below shows pw_watch building for a STMicroelectronics STM32F429I-DISC1
-development board, flashing the board with the affected test, and verifying the
-test runs as expected. Once this is set up, you can attach multiple devices to
-run tests in a distributed manner to reduce the time it takes to run tests.
+The demo below shows `pw_watch` building for a STMicroelectronics
+STM32F429I-DISC1 development board, flashing the board with the affected test,
+and verifying the test runs as expected. Once this is set up, you can attach
+multiple devices to run tests in a distributed manner to reduce the time it
+takes to run tests.
-## pw_presubmit
+## `pw_presubmit` - Vacuum code lint on every commit
Presubmit checks are essential tools, but they take work to set up, and projects
-don’t always get around to it. The pw_presubmit module provides tools for
+don’t always get around to it. The `pw_presubmit` module provides tools for
setting up high quality presubmit checks for any project. We use this framework
to run Pigweed’s presubmit on our workstations and in our automated building
tools.
-The pw_presubmit module includes pw format, a tool that provides a unified
-interface for automatically formatting code in a variety of languages. With pw
-format, you can format C, C++, Python, GN, and Go code according to
-configurations defined by your project. pw format leverages existing tools like
-clang-format, and it’s simple to add support for new languages.
+The `pw_presubmit` module includes `pw format` command, a tool that provides a
+unified interface for automatically formatting code in a variety of languages.
+With `pw format`, you can format C, C++, Python, GN, and Go code according to
+configurations defined by your project. `pw format` leverages existing tools
+like `clang-format`, and it’s simple to add support for new languages.
-## pw_env_setup
+## `pw_env_setup` - Cross platform embedded compiler setup
A classic problem in the embedded space is reducing the time from git clone to
having a binary executing on a device. The issue is that an entire suite of
@@ -77,7 +75,7 @@
systems development where one frequently needs access to native system resources
like USB devices, or must operate on Windows.
-env_setup is our compromise solution for this problem that works on Mac,
+`pw_env_setup` is our compromise solution for this problem that works on Mac,
Windows, and Linux. It leverages the Chrome packaging system CIPD to bootstrap a
Python installation, which in turn inflates a virtual environment. The tooling
is installed into your workspace, and makes no changes to your system. This
@@ -85,38 +83,52 @@
-## pw_unit_test
+## `pw_unit_test` - Embedded testing for MCUs
Unit testing is important, and Pigweed offers a portable library that’s broadly
compatible with [Google Test](https://github.com/google/googletest). Unlike
-Google Test, pw_unit_test is built on top of embedded friendly primitives; for
+Google Test, `pw_unit_test` is built on top of embedded friendly primitives; for
example, it does not use dynamic memory allocation. Additionally, it is easy to
port to new target platforms by implementing the
[test event handler interface](https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test/public/pw_unit_test/event_handler.h).
+Like other modules in Pigweed, `pw_unit_test` is designed for use in
+established codebases with their own build system, without the rest of Pigweed
+or the Pigweed integrated GN build. However, when combined with Pigweed's
+build, the result is a flexible and powerful setup that enables easily
+developing code on your desktop (with tests), then running the same tests
+on-device.
+
## And more!
- - **pw_cpu_exception_armv7m**: Robust low level hardware fault handler for ARM
+See the "Module Guides" in the documentation for the complete list and
+documentation for each, but is a selection of some others:
+
+ - `pw_cpu_exception_armv7m`: Robust low level hardware fault handler for ARM
Cortex-M; the handler even has unit tests written in assembly to verify
nested-hardware-fault handling!
- - **pw_polyfill**: Similar to JavaScript “polyfill” libraries, this module
+ - `pw_polyfill`: Similar to JavaScript “polyfill” libraries, this module
provides selected C++17 standard library components that are compatible with
C++11 and C++14.
- - **pw_minimal_cpp_stdlib**: An entirely incomplete implementation of the C++17
+ - `pw_minimal_cpp_stdlib`: An entirely incomplete implementation of the C++17
standard library, that provides some of the primitives needed by Pigweed
itself. Useful for projects that want to use Pigweed, but don’t enable the
typical standard C++ libraries like GNU’s libstdc++ or LLVM’s libc++. Don’t
use this module unless you know what you are doing.
- - **pw_kvs**: A key-value-store implementation for flash-backed persistent
+ - `pw_tokenizer`: Replace string literals from log statements with 32-bit
+ tokens, to reduce flash use, reduce logging bandwidth, and save formatting
+ cycles from log statements at runtime.
+
+ - `pw_kvs`: A key-value-store implementation for flash-backed persistent
storage with integrated wear levelling. This is a lightweight alternative to
a file system for embedded devices.
- - **pw_protobuf**: An early preview of our wire-format-oriented protocol buffer
+ - `pw_protobuf`: An early preview of our wire-format-oriented protocol buffer
implementation. This protobuf compiler makes a different set of
implementation tradeoffs than the most popular protocol buffer library in
this space, nanopb.
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 3b5162b..3e8e1b6 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -27,7 +27,7 @@
sources = [
"embedded_cpp_guide.rst",
"getting_started.md",
- "module_guide.rst",
+ "module_structure.rst",
"style_guide.rst",
]
}
@@ -44,7 +44,7 @@
"../CONTRIBUTING.md",
"../README.md",
"index.rst",
- "modules.rst",
+ "module_guides.rst",
"targets.rst",
]
output_directory = target_gen_dir
diff --git a/docs/getting_started.md b/docs/getting_started.md
index f328871..21f351d 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -4,11 +4,95 @@
We hope to make the setup process as smooth as possible. If any of this doesn't
work, please [file a bug](https://bugs.chromium.org/p/pigweed/issues/entry).
+## Express setup
+
+If you're impatient, below is the shorter version of getting setup for Pigweed.
+If you run into trouble, look at the more in-depth guide below, starting at
+"Prerequisites". The express setup configures Pigweed's watcher for three
+targets to give a taste of Pigweed:
+
+1. **Host** - Mac, Linux, or Windows. Builds and runs tests
+2. **Device/STM32F429** - Build only; see later in the guide to run tests on
+ device
+3. **Docs** - Builds the Pigweed docs
+
+To get setup:
+
+(1) Make sure you have Git and Python installed and on your path.
+
+(2) Clone Pigweed and bootstrap the environment (compiler setup & more). **Be
+ patient, this step downloads ~1GB of LLVM, GCC, and other tooling**.
+
+```bash
+$ cd ~
+$ git clone https://pigweed.googlesource.com/pigweed/pigweed
+...
+$ cd pigweed
+$ . ./bootstrap.sh
+...
+```
+
+(3) Configure the three target GN builds: host, device, and docs.
+
+```bash
+$ gn gen out/host
+Done. Made 275 targets from 67 files in 417ms
+$ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
+Done. Made 220 targets from 65 files in 424ms
+$ gn gen --args='pw_target_config = "//targets/docs/target_config.gni"' out/docs
+Done. Made 284 targets from 65 files in 415ms
+```
+
+(4) Start the watcher. The watcher will invoke Ninja to build all the targets
+
+```bash
+$ pw watch
+
+ ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄
+ ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌
+ ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌
+ ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌
+ ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀
+
+20200319 01:41:37 INF Starting Pigweed build watcher
+20200319 01:41:37 INF Searching for GN build dirs...
+20200319 01:41:37 INF Will build [1/3]: out/host
+20200319 01:41:37 INF Will build [2/3]: out/disco
+20200319 01:41:37 INF Will build [3/3]: out/docs
+20200319 01:41:39 INF Directory to watch: $HOME/wrk/pigweed
+20200319 01:41:39 INF Watching for file changes. Ctrl-C exits.
+20200319 01:41:39 INF Triggering initial build...
+...
+```
+
+(5) **Congratulations, you're ready to go!** Now take Pigweed for a spin with
+ the below steps.
+
+(6) With the watcher running in a separate window, edit
+ `pw_status/status_test.cc` to make an expectation fail; for example, add
+ `EXPECT_EQ(0, 1);` in a test.
+
+(7) Save the file. Observe the watcher rebuild & retest, and fail. Restore the
+ test if you feel like it.
+
+(8) Open the generated docs in `out/docs/gen/docs/html/index.html` in your
+ browser.
+
+(9) Edit `docs/getting_started.md` (this file!) and make any change. Save. See
+ the watcher rebuild the docs. Reload your browser, and see the changes.
+
+See below for equivalent Windows commands, and for more details on what each
+part does.
+
+**Note:** After running bootstrap once, use `. ./activate.sh` (or
+`activate.bat` on Windows) to re-activate the environment without
+re-bootstrapping.
+
## Prerequisites
**Linux**<br/>
-Linux should work out of box, and not require any manual installation of
-prerequisites.
+Most Linux installations should work out of box, and not require any manual
+installation of prerequisites beyond basics like `git` and `build-essential`.
**macOS**<br/>
macOS does not require any prerequisites to be installed, but you may run into
@@ -165,8 +249,7 @@
**Windows**
```batch
-> gn gen out/disco
-> echo pw_target_config = ^"//targets/stm32f429i-disc1/target_config.gni^">> out\disco\args.gn
+> gn gen "pw_target_config = ""//targets/stm32f429i-disc1/target_config.gni""" out/disco
```
Switch to the window running `pw_watch`, and quit using `ctrl+c`.
@@ -242,8 +325,7 @@
**Windows**
```batch
-> gn gen out/docs
-> echo pw_target_config = ^"//targets/docs/target_config.gni^">> out\docs\args.gn
+> gn gen --args="pw_target_config = ""//targets/docs/target_config.gni""" out/docs
```
Once again, either restart `pw_watch`, or manually run `ninja -C out/docs`. When
diff --git a/docs/index.rst b/docs/index.rst
index c42abc8..d8b5e12 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,11 +9,11 @@
:hidden:
Home <self>
+ docs/getting_started.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
- docs/getting_started.md
docs/embedded_cpp_guide
docs/style_guide
- docs/module_guide
targets
- modules
+ docs/module_structure
+ module_guides
diff --git a/docs/modules.rst b/docs/module_guides.rst
similarity index 69%
rename from docs/modules.rst
rename to docs/module_guides.rst
index e253c7e..728deff 100644
--- a/docs/modules.rst
+++ b/docs/module_guides.rst
@@ -1,8 +1,9 @@
-=======
-Modules
-=======
+=============
+Module Guides
+=============
Pigweed is a collection of embedded-focused and embedded-related modules.
-Modules may contain code from multiple languages, including C, C++, and Python.
+Modules may contain code from multiple languages, including C, C++, Go, Rust,
+Shell, Batch and Python.
.. toctree::
:maxdepth: 1
diff --git a/docs/module_guide.rst b/docs/module_structure.rst
similarity index 98%
rename from docs/module_guide.rst
rename to docs/module_structure.rst
index 594dc96..5a5858e 100644
--- a/docs/module_guide.rst
+++ b/docs/module_structure.rst
@@ -4,9 +4,9 @@
.. _chapter-module-guide:
--------------------
-What's in a module?
--------------------
+----------------
+Module Structure
+----------------
The Pigweed module structure is designed to keep as much code as possible for a
particular slice of functionality in one place. That means including the code
from multiple languages, as well as all the related documentation and tests.
diff --git a/docs/style_guide.rst b/docs/style_guide.rst
index 285ded8..f69f2a3 100644
--- a/docs/style_guide.rst
+++ b/docs/style_guide.rst
@@ -208,7 +208,7 @@
.. code-block:: cpp
- // Copyright 2019 The Pigweed Authors
+ // Copyright 2020 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
diff --git a/pw_presubmit/docs.rst b/pw_presubmit/docs.rst
index a8d1ff1..be568c8 100644
--- a/pw_presubmit/docs.rst
+++ b/pw_presubmit/docs.rst
@@ -11,6 +11,22 @@
checking and fixing code format. It also includes the presubmit check script for
the Pigweed repository, ``pigweed_presubmit.py``.
+Presubmit checks are essential tools, but they take work to set up, and
+projects don’t always get around to it. The ``pw_presubmit`` module provides
+tools for setting up high quality presubmit checks for any project. We use this
+framework to run Pigweed’s presubmit on our workstations and in our automated
+building tools.
+
+The ``pw_presubmit`` module also includes ``pw format``, a tool that provides a
+unified interface for automatically formatting code in a variety of languages.
+With ``pw format``, you can format C, C++, Python, GN, and Go code according to
+configurations defined by your project. ``pw format`` leverages existing tools
+like ``clang-format``, and it’s simple to add support for new languages.
+
+.. image:: ../docs/images/pw_presubmit_demo.gif
+ :alt: ``pw format`` demo
+ :align: left
+
Compatibility
=============
Python 3
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst
index 09f742d..1f5005c 100644
--- a/pw_tokenizer/docs.rst
+++ b/pw_tokenizer/docs.rst
@@ -578,8 +578,8 @@
TransmitLogMessage(base64_buffer, base64_size);
}
-War story: deploying tokenized logging to an in-development product
-===================================================================
+Deployment war story
+====================
The tokenizer module was developed to bring tokenized logging to an
in-development product. The product already had an established text-based
logging system. Deploying tokenization was straightforward and had substantial