Docs: Merge setup and developer guide
Merges setup and developer guide docs to have a single, unified getting
started guide.
Change-Id: Iae2324a99561ea6719f5d32a08f3e500e7e14130
diff --git a/README.md b/README.md
index b772fb2..c099ecd 100644
--- a/README.md
+++ b/README.md
@@ -16,9 +16,7 @@
# Getting Started
If you'd like to get set up with Pigweed, please visit the
-[setup guide](docs/setup.md), and then check out the
-[Pigweed developer's guide](docs/developer_guide.md) for more information on how
-to get the most out of Pigweed.
+[getting started guide](docs/getting_started.md).
# What does Pigweed offer?
@@ -85,6 +83,7 @@
is installed into your workspace, and makes no changes to your system. This
tooling is designed to be reused by any project.
+
## pw_unit_test
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index e32f4b8..fd9cfe4 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -16,6 +16,7 @@
pw_doc_group("core_docs") {
inputs = [
+ "images/pw_env_setup_demo.gif",
"images/pw_presubmit_demo.gif",
"images/pw_status_test.png",
"images/pw_watch_build_demo.gif",
@@ -24,9 +25,8 @@
"images/stm32f429i-disc1_connected.jpg",
]
sources = [
- "developer_guide.md",
"embedded_cpp_guide.rst",
- "setup.md",
+ "getting_started.md",
"style_guide.rst",
]
}
diff --git a/docs/developer_guide.md b/docs/getting_started.md
similarity index 66%
rename from docs/developer_guide.md
rename to docs/getting_started.md
index a9ba1d8..9edefc8 100644
--- a/docs/developer_guide.md
+++ b/docs/getting_started.md
@@ -1,15 +1,94 @@
-# Pigweed Developer Guide
+# Getting started
-Pigweed is an assortment of tooling and libraries for embedded projects. One
-of the key goals is that you may chose to use things from Pigweed in an *à la
-carte* fashion. Pigweed is a bundle of helper libraries, but it doesn't provide
-an application image that can be run on a device. Because of this, the binaries
-produced when building upstream Pigweed are unit tests (which can be directly
-flashed to a device and run) and host tools.
+## Initial Setup
-If you haven't already, you'll need to go through the [Pigweed setup](setup.md)
-process to ensure you have the necessary tools before running the commands
-throughout this guide.
+Pigweed uses a combination of CIPD and Python virtual environments to provide
+you with the tools necessary for Pigweed development without modifying your
+system's development environment. This guide will walk you through the steps
+needed to download and set up the Pigweed repository.
+
+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).
+
+### Prerequisites
+
+**Linux**<br/>
+Linux should work out of box, and not require any manual installation of
+prerequisites.
+
+**macOS**<br/>
+macOS does not require any prerequisites to be installed, but you may run into
+some Mac-specific configuration issues when you begin the bootstrap process.
+
+If you're using Homebrew and you get an error saying
+`module 'http.client' has no attribute 'HTTPSConnection'` then your
+Homebrew Python was not set up to support SSL. Ensure it's installed with
+`brew install openssl` and then run
+`brew uninstall python && brew install python`.
+
+To flash firmware to a STM32 Discovery development board (and run `pw test`)
+from macOS, you will need to install OpenOCD. Install Homebrew using the latest
+instructions at https://brew.sh/, then install OpenOCD with
+`brew install openocd`.
+
+**Windows**<br/>
+To start using Pigweed on Windows, you'll need to install Git and Python (2.7 or
+above). We recommend you install Git to run from the command line and third
+party software.
+
+### Setup
+
+Once you have prerequisites satisfied, you should be able to clone Pigweed and
+run the bootstrap that initializes the Pigweed virtual environment.
+
+**Linux/macOS**
+```bash
+$ git clone sso://pigweed.googlesource.com/pigweed/pigweed ~/pigweed
+$ cd ~/pigweed
+$ . bootstrap.sh
+```
+
+**Windows**
+```batch
+:: Run git commands from the shell you set up to use with Git during install.
+> cd %HOMEPATH%\pigweed
+> git clone sso://pigweed.googlesource.com/pigweed/pigweed
+> bootstrap.bat
+```
+
+Below is a real-time demo with roughly what you should expect to see as output:
+
+
+### Contributors
+
+If you plan to contribute to Pigweed, you'll need to set up a commit hook for
+Gerrit.
+
+**Linux/macOS**<br/>
+```bash
+$ f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
+```
+
+**Windows**<br/>
+Download [the Gerrit commit hook](https://gerrit-review.googlesource.com/tools/hooks/commit-msg)
+and then copy it to the `.git\hooks` directory in the Pigweed repository.
+```batch
+copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg
+```
+
+All Pigweed CLs must adhere to Pigweed's style guide and pass automated builds,
+tests, and style checks to be merged upstream. Much of this checking is done
+using Pigweed's pw_presubmit module. To speed up the review process, consider
+adding `pw presubmit` as a git push hook using the following command:
+
+**Linux/macOS**<br/>
+```bash
+$ pw presubmit --install
+```
+
+### Congratulations!
+
+You are now set up to start using Pigweed!
## Pigweed Environment
@@ -35,6 +114,13 @@
## Building Pigweed With GN
+Pigweed is an assortment of tooling and libraries for embedded projects. One
+of the key goals is that you may chose to use things from Pigweed in an *à la
+carte* fashion. Pigweed is a bundle of helper libraries, but it doesn't provide
+an application image that can be run on a device. Because of this, the binaries
+produced when building upstream Pigweed are unit tests (which can be directly
+flashed to a device and run) and host tools.
+
Pigweed's primary build system is GN/Ninja based. There are
CMake and Bazel builds in-development, but they are incomplete and don't have
feature parity with the GN build. We strongly recommend you stick to the GN
@@ -106,7 +192,9 @@
- **Docs** (//targets/docs/target_config.gni): Builds these docs! This requires
a build target because of the binary size reporting automatically generated
- with the documents.
+ with the documents. Docs are output to `[build directory]/gen/docs/html`,
+ where `[build directory]` is the output directory specified in `gn gen` (see
+ below on setting a build target).
- **STM32F429I-DISC1** (//targets/stm32f429i-disc1/target_config.gni): Builds
unit tests for STMicroelectronics's Discovery development board (MPN:
@@ -124,7 +212,8 @@
To set the target configuration for a build, set the `pw_target_config` GN build
arg to point to the target configuration `.gni` file you wish to use.
-In this example, we generating Ninja build files for the stm32f429i-disc1.
+In this example, we generate Ninja build files for the stm32f429i-disc1 to
+`out/disco`.
```bash
$ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
```
@@ -177,6 +266,10 @@
Whenever you make code changes and trigger a build, all the affected unit tests
will be run across the attached boards!
+See the demo below for an example of what this all looks like put together:
+
+
+
## Next steps
This concludes the introduction to developing with Pigweed. If you'd like to see
diff --git a/docs/images/pw_env_setup_demo.gif b/docs/images/pw_env_setup_demo.gif
new file mode 100644
index 0000000..c8942ac
--- /dev/null
+++ b/docs/images/pw_env_setup_demo.gif
Binary files differ
diff --git a/docs/index.rst b/docs/index.rst
index 1b33054..ec51171 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,8 +10,7 @@
Home <self>
CODE_OF_CONDUCT.md
- docs/setup.md
- docs/developer_guide.md
+ docs/getting_started.md
docs/embedded_cpp_guide
docs/style_guide
targets
diff --git a/docs/setup.md b/docs/setup.md
deleted file mode 100644
index 56bdf52..0000000
--- a/docs/setup.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Setup
-
-Pigweed uses a combination of CIPD and Python virtual environments to provide
-you with the tools necessary for Pigweed development without modifying your
-system's development environment. This guide will walk you through the steps
-needed to download and set up the Pigweed repository.
-
-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).
-
-## Prerequisites
-
-**Linux**<br/>
-Linux should work out of box, and not require any manual installation of
-prerequisites.
-
-**macOS**<br/>
-macOS does not require any prerequisites to be installed, but you may run into
-some Mac-specific configuration issues when you begin the bootstrap process.
-
-If you're using Homebrew and you get an error saying
-`module 'http.client' has no attribute 'HTTPSConnection'` then your
-Homebrew Python was not set up to support SSL. Ensure it's installed with
-`brew install openssl` and then run
-`brew uninstall python && brew install python`.
-
-To flash firmware to a STM32 Discovery development board (and run `pw test`)
-from macOS, you will need to install OpenOCD. Install Homebrew using the latest
-instructions at https://brew.sh/, then install OpenOCD with
-`brew install openocd`.
-
-**Windows**<br/>
-To start using Pigweed on Windows, you'll need to install Git and Python (2.7 or
-above). We recommend you install Git to run from the command line and third
-party software.
-
-## Setup
-
-Once you have prerequisites satisfied, you should be able to clone Pigweed and
-run the bootstrap that initializes the Pigweed virtual environment.
-
-**Linux/macOS**
-```bash
-$ git clone sso://pigweed.googlesource.com/pigweed/pigweed ~/pigweed
-$ cd ~/pigweed
-$ . bootstrap.sh
-```
-
-**Windows**
-```batch
-:: Run git commands from the shell you set up to use with Git during install.
-> cd %HOMEPATH%\pigweed
-> git clone sso://pigweed.googlesource.com/pigweed/pigweed
-> bootstrap.bat
-```
-
-## Contributors
-
-If you plan to contribute to Pigweed, you'll need to set up a commit hook for
-Gerrit.
-
-**Linux/macOS**<br/>
-```bash
-$ f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
-```
-
-**Windows**<br/>
-Download [the Gerrit commit hook](https://gerrit-review.googlesource.com/tools/hooks/commit-msg)
-and then copy it to the `.git\hooks` directory in the Pigweed repository.
-```batch
-copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg
-```
-
-All Pigweed CLs must adhere to Pigweed's style guide and pass automated builds,
-tests, and style checks to be merged upstream. Much of this checking is done
-using Pigweed's pw_presubmit module. To speed up the review process, consider
-adding `pw presubmit` as a git push hook using the following command:
-
-**Linux/macOS**<br/>
-```bash
-$ pw presubmit --install
-```
-
-## Congratulations!
-You should now be set up to start using Pigweed. If you are interested in seeing
-some of what Pigweed can do, check out the [developer guide](developer_guide.md).
