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/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
