docs: Migrate MD to RST
This migrates our legacy Markdown to Restructured Text (RST). Now that
we have a website, we don't have to rely on rendering our docs on Gerrit
and GitHub, and can instead point at our webpage. This enables
1. Upgrading to a new Sphinx - our current version is 2 years old.
2. Using more sophisticated constructs like "note"
3. Adding custom CSS rules
Change-Id: I8153322efbcb307c1ca1ee3392b67f30f365f78c
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/40480
Reviewed-by: Armando Montanez <amontanez@google.com>
Commit-Queue: Keir Mierle <keir@google.com>
Pigweed-Auto-Submit: Keir Mierle <keir@google.com>
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index 551d804..0000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of
-experience, education, socio-economic status, nationality, personal appearance,
-race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
- address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
- professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, or to ban temporarily or permanently any
-contributor for other behaviors that they deem inappropriate, threatening,
-offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-This Code of Conduct also applies outside the project spaces when the Project
-Steward has a reasonable belief that an individual's behavior may have a
-negative impact on the project or its community.
-
-## Conflict Resolution
-
-We do not believe that all conflict is bad; healthy debate and disagreement
-often yield positive results. However, it is never okay to be disrespectful or
-to engage in behavior that violates the project’s code of conduct.
-
-If you see someone violating the code of conduct, you are encouraged to address
-the behavior directly with those involved. Many issues can be resolved quickly
-and easily, and this gives people more control over the outcome of their
-dispute. If you are unable to resolve the matter for any reason, or if the
-behavior is threatening or harassing, report it. We are dedicated to providing
-an environment where participants feel welcome and safe.
-
-Reports should be directed to Pigweed Community Managers at
-pigweed-community-managers@google.com, the Project Steward(s) for Pigweed. It
-is the Project Steward’s duty to receive and address reported violations of the
-code of conduct. They will then work with a committee consisting of
-representatives from the Open Source Programs Office and the Google Open Source
-Strategy team. If for any reason you are uncomfortable reaching out the Project
-Steward, please email opensource@google.com.
-
-We will investigate every complaint, but you may not receive a direct response.
-We will use our discretion in determining when and how to follow up on reported
-incidents, which may range from not taking action to permanent expulsion from
-the project and project-sponsored spaces. We will notify the accused of the
-report and provide them an opportunity to discuss it before any action is taken.
-The identity of the reporter will be omitted from the details of the report
-supplied to the accused. In potentially harmful situations, such as ongoing
-harassment or threats to anyone's safety, we may take action without notice.
-
-## Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
-available at
-https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index d9e325f..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# Contributing
-
-We'd love to accept your patches and contributions to Pigweed. There are just a
-few small guidelines you need to follow. Before making or sending major changes,
-please reach out on the [mailing list](mailto:pigweed@googlegroups.com) first to
-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/).
- * Verify that Git user email (git config user.email) is either Google Account
- email or an Alternate email for the Google account used to sign the CLA (Manage
- Google account->Personal Info->email).
- * 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).
- 1. Ensure all files include a correct [copyright and license header](CONTRIBUTING.md#source-code-headers).
- 1. Include any necessary changes to
- [documentation](CONTRIBUTING.md#documentation).
- 1. Run `pw presubmit` (see below) to detect style or compilation issues before
- uploading.
- 1. Upload the change with `git push origin HEAD:refs/for/master`.
- 1. Address any reviewer feedback by amending the commit (`git commit --amend`).
- 1. Submit change to CI builders to merge. If you are not part of Pigweed's
- core team, you can ask the reviewer to add the `+2 CQ` vote, which will
- trigger a rebase and submit once the builders pass.
-
-## Contributor License Agreement
-
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
-
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
-
-## Gerrit Commit Hook
-
-Gerrit requires all changes to have a `Change-Id` tag at the bottom of each
-commit message. You should set this up to be done automatically using the
-instructions below.
-
-**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
-```
-
-## Documentation
-
-All Pigweed changes must either
-
- 1. Include updates to documentation, or
- 1. Include `No-Docs-Update-Reason: <reason>` in the commit message or a Gerrit
- comment on the CL. Potential reasons might include
- * "minor code formatting change",
- * "internal cleanup of pw_modulename, no changes to API"
-
-It's acceptable to only document new changes in an otherwise underdocumented
-module, but it's not acceptable to not document new changes because the module
-doesn't have any other documentation.
-
-## Code Reviews
-
-All Pigweed development happens on Gerrit, following the [typical Gerrit
-development workflow](http://ceres-solver.org/contributing.html). Consult
-[Gerrit User Guide](https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html)
-for more information on using Gerrit.
-
-In the future we may support GitHub pull requests, but until that time we will
-close GitHub pull requests and ask that the changes be uploaded to Gerrit
-instead.
-
-## Community Guidelines
-
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google/conduct/) and the [Pigweed Code of
-Conduct](CODE_OF_CONDUCT.md).
-
-## Source Code Headers
-
-Every Pigweed file containing source code must include copyright and license
-information. This includes any JS/CSS files that you might be serving out to
-browsers.
-
-Apache header for C and C++ files:
-
-```javascript
-// 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
-// the License at
-//
-// https://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-// License for the specific language governing permissions and limitations under
-// the License.
-```
-
-Apache header for Python and GN files:
-
-```python
-# 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
-# the License at
-#
-# https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations under
-# the License.
-```
-
-## Presubmit Checks and Continuous Integration
-
-All Pigweed change lists (CLs) must adhere to Pigweed's style guide and pass a
-suite of automated builds, tests, and style checks to be merged upstream. Much
-of this checking is done using Pigweed's `pw_presubmit` module by automated
-builders. These builders run before each Pigweed CL is submitted and in our
-continuous integration infrastructure (see
-https://ci.chromium.org/p/pigweed/g/pigweed/console).
-
-### Running Presubmit Checks
-
-To run automated presubmit checks on a pending CL, click the `CQ DRY RUN` button
-in the Gerrit UI. The results appear in the Tryjobs section, below the source
-listing. Jobs that passed are green; jobs that failed are red.
-
-If all checks pass, you will see a ``Dry run: This CL passed the CQ dry run.``
-comment on your change. If any checks fail, you will see a ``Dry run: Failed
-builds:`` message. All failures must be addressed before submitting.
-
-In addition to the publicly visible presubmit checks, Pigweed runs internal
-presubmit checks that are only visible within Google. If any these checks fail,
-external developers will see a ``Dry run: Failed builds:`` comment on the CL,
-even if all visible checks passed. Reach out to the Pigweed team for help
-addressing these issues.
-
-### Project Presubmit Checks
-
-In addition to Pigweed's presubmit checks, some projects that use Pigweed run
-their presubmit checks in Pigweed's infrastructure. This supports a development
-flow where projects automatically update their Pigweed submodule if their tests
-pass. If a project cannot build against Pigweed's tip-of-tree, it will stay on a
-fixed Pigweed revision until the issues are fixed. See the
-[sample project](https://pigweed.googlesource.com/pigweed/sample_project/) for
-an example of this.
-
-Pigweed does its best to keep builds passing for dependent projects. In some
-circumstances, the Pigweed maintainers may choose to merge changes that break
-dependent projects. This will only be done if
-
- * a feature or fix is needed urgently in Pigweed or for a different project,
- and
- * the project broken by the change does not imminently need Pigweed updates.
-
-The downstream project will continue to build against their last working
-revision of Pigweed until the incompatibilities are fixed.
-
-In these situations, Pigweed's commit queue submission process will fail for all
-changes. If a change passes all presubmit checks except for known failures, the
-Pigweed team may permit manual submission of the CL. Contact the Pigweed team
-for submission approval.
-
-### Running local presubmits
-
-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
-```
-
-This will be effectively the same as running the following command before every
-`git push`:
-```bash
-$ pw presubmit
-```
-
-
-
-If you ever need to bypass the presubmit hook (due to it being broken, for
-example) you may push using this command:
-
-```bash
-$ git push origin HEAD:refs/for/master --no-verify
-```
diff --git a/README.md b/README.md
index 9f73d55..3c6da1d 100644
--- a/README.md
+++ b/README.md
@@ -1,142 +1 @@
-# Pigweed
-
-Pigweed is an open source collection of embedded-targeted libraries--or as we
-like to call them, modules. These modules are building blocks and infrastructure
-that enable faster and more reliable development on small-footprint MMU-less
-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
-value developer feedback along the way.
-
-# Quick links
-
- - [Getting started guide](docs/getting_started.md)
- - [Documentation](https://pigweed.dev)
- - [Source code](https://cs.opensource.google/pigweed/pigweed)
- - [Code reviews](https://pigweed-review.googlesource.com/)
- - [Issue tracker](https://bugs.pigweed.dev/)
- - [Mailing list](https://groups.google.com/forum/#!forum/pigweed)
- - [Chat room (Discord)](https://discord.gg/M9NSeTA)
- - [Open Source blog post](https://opensource.googleblog.com/2020/03/pigweed-collection-of-embedded-libraries.html)
-
-Get the code: `git clone https://pigweed.googlesource.com/pigweed/pigweed` (or
-[fork us on GitHub](https://github.com/google/pigweed)).
-
-# Getting Started
-
-If you'd like to get set up with Pigweed, please visit the
-[getting started guide](docs/getting_started.md).
-
-# What does Pigweed offer?
-
-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 "Module Guides" section in the full
-documentation.
-
-## `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
-the embedded space, file system watchers are less prevalent; however, they are
-no less useful! The Pigweed watcher module makes it easy to instantly compile,
-flash, and run tests upon save. Combined with the GN-based build which expresses
-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.
-
-
-
-## `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
-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` 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` - 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
-tools is needed for non-trivial production embedded projects. For example:
-
- - A C++ compiler for your target device, and also for your host
- - A build system or three; for example, GN, Ninja, CMake, Bazel
- - A code formatting program like clang-format
- - A debugger like OpenOCD to flash and debug your embedded device
- - A known Python version with known modules installed for scripting
- - A Go compiler for the Go-based command line tools
- - ... and so on
-
-In the server space, container solutions like Docker or Podman solve this;
-however, in our experience container solutions are a mixed bag for embedded
-systems development where one frequently needs access to native system resources
-like USB devices, or must operate on Windows.
-
-`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
-tooling is designed to be reused by any project.
-
-
-
-## `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
-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!
-
-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_cortex_m`: 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
- provides selected C++17 standard library components that are compatible with
- C++11 and C++14.
-
- - `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
- implementation. This protobuf compiler makes a different set of
- implementation tradeoffs than the most popular protocol buffer library in
- this space, nanopb.
+See our website: http://pigweed.dev
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 3c1baae..d8d7652 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -16,6 +16,8 @@
import("$dir_pw_docgen/docs.gni")
+# Note: These may be useful for downstream projects, which is why they are
+# split out from the overall docgen target below.
pw_doc_group("core_docs") {
inputs = [
"images/pw_env_setup_demo.gif",
@@ -26,9 +28,11 @@
"images/stm32f429i-disc1_connected.jpg",
]
sources = [
+ "code_of_conduct.rst",
+ "contributing.rst",
"embedded_cpp_guide.rst",
"faq.rst",
- "getting_started.md",
+ "getting_started.rst",
"module_structure.rst",
"style_guide.rst",
]
@@ -135,9 +139,6 @@
pw_doc_gen("docs") {
conf = "conf.py"
sources = [
- "../CODE_OF_CONDUCT.md",
- "../CONTRIBUTING.md",
- "../README.md",
"build_system.rst",
"index.rst",
"module_guides.rst",
diff --git a/docs/code_of_conduct.rst b/docs/code_of_conduct.rst
new file mode 100644
index 0000000..79436db
--- /dev/null
+++ b/docs/code_of_conduct.rst
@@ -0,0 +1,98 @@
+.. _docs-code-of-conduct:
+
+===============
+Code of Conduct
+===============
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+Our Standards
+-------------
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+Our Responsibilities
+--------------------
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Scope
+-----
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event. Representation of a
+project may be further defined and clarified by project maintainers.
+
+This Code of Conduct also applies outside the project spaces when the Project
+Steward has a reasonable belief that an individual's behavior may have a
+negative impact on the project or its community.
+
+Conflict Resolution
+-------------------
+We do not believe that all conflict is bad; healthy debate and disagreement
+often yield positive results. However, it is never okay to be disrespectful or
+to engage in behavior that violates the project’s code of conduct.
+
+If you see someone violating the code of conduct, you are encouraged to address
+the behavior directly with those involved. Many issues can be resolved quickly
+and easily, and this gives people more control over the outcome of their
+dispute. If you are unable to resolve the matter for any reason, or if the
+behavior is threatening or harassing, report it. We are dedicated to providing
+an environment where participants feel welcome and safe.
+
+Reports should be directed to Pigweed Community Managers at
+pigweed-community-managers@google.com, the Project Steward(s) for Pigweed. It
+is the Project Steward’s duty to receive and address reported violations of the
+code of conduct. They will then work with a committee consisting of
+representatives from the Open Source Programs Office and the Google Open Source
+Strategy team. If for any reason you are uncomfortable reaching out the Project
+Steward, please email opensource@google.com.
+
+**We will investigate every complaint**, but you may not receive a direct
+response. We will use our discretion in determining when and how to follow up
+on reported incidents, which may range from not taking action to permanent
+expulsion from the project and project-sponsored spaces. We will notify the
+accused of the report and provide them an opportunity to discuss it before any
+action is taken. The identity of the reporter will be omitted from the details
+of the report supplied to the accused. In potentially harmful situations, such
+as ongoing harassment or threats to anyone's safety, we may take action without
+notice.
+
+Attribution
+-----------
+This Code of Conduct is adapted from `Contributor Covenant version 1.4
+<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>`_
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..d9a7fce
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,236 @@
+.. _docs-contributing:
+
+============
+Contributing
+============
+We'd love to accept your patches and contributions to Pigweed. There are just a
+few small guidelines you need to follow. Before making or sending major
+changes, please reach out on the `mailing list
+<https://groups.google.com/forum/#!forum/pigweed>`_ first to 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
+:ref:`docs-code-of-conduct`. We expect everyone who interacts with the project
+to respect these guidelines.
+
+Pigweed contribution overview
+-----------------------------
+
+#. One-time contributor setup:
+
+ - Sign the `Contributor License Agreement <https://cla.developers.google.com/>`_.
+ - Verify that your Git user email (git config user.email) is either Google
+ Account email or an Alternate email for the Google account used to sign
+ the CLA (Manage Google account → Personal Info → email)
+ - Install the Gerrit commit hook to automatically add a ``Change-Id: ...``
+ line to your commit
+ - Install the Pigweed presubmit check hook with ``pw presubmit --install``
+
+#. Ensure all files include the correct copyright and license headers
+#. Include any necessary changes to the documentation
+#. Run :ref:`module-pw_presubmit` to detect style or compilation issues before
+ uploading
+#. Upload the change with ``git push origin HEAD:refs/for/master``
+#. Address any reviewer feedback by amending the commit (``git commit --amend``)
+#. Submit change to CI builders to merge. If you are not part of Pigweed's
+ core team, you can ask the reviewer to add the `+2 CQ` vote, which will
+ trigger a rebase and submit once the builders pass
+
+.. note::
+
+ If you have any trouble with this flow, reach out in our `chat room
+ <https://discord.gg/M9NSeTA>`_ or on the `mailing list
+ <https://groups.google.com/forum/#!forum/pigweed>`_ for help.
+
+Contributor License Agreement
+-----------------------------
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+Gerrit Commit Hook
+------------------
+Gerrit requires all changes to have a ``Change-Id`` tag at the bottom of each
+commit message. You should set this up to be done automatically using the
+instructions below.
+
+**Linux/macOS**
+
+.. code:: 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**
+
+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.
+
+.. code::
+
+ copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg
+
+Documentation
+-------------
+
+All Pigweed changes must either
+
+#. Include updates to documentation, or
+#. Include ``No-Docs-Update-Reason: <reason>`` in the commit message or a
+ Gerrit comment on the CL. For example:
+
+ * ``No-Docs-Update-Reason: formatting tweaks``
+ * ``No-Docs-Update-Reason: internal cleanups``
+ * ``No-Docs-Update-Reason: bugfix``
+
+It's acceptable to only document new changes in an otherwise underdocumented
+module, but it's not acceptable to not document new changes because the module
+doesn't have any other documentation.
+
+Code Reviews
+------------
+All Pigweed development happens on Gerrit, following the `typical Gerrit
+development workflow <http://ceres-solver.org/contributing.html>`_. Consult the
+`Gerrit User Guide
+<https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html>`_
+for more information on using Gerrit.
+
+In the future we may support GitHub pull requests, but until that time we will
+close GitHub pull requests and ask that the changes be uploaded to Gerrit
+instead.
+
+Community Guidelines
+--------------------
+This project follows `Google's Open Source Community Guidelines
+<https://opensource.google/conduct/>`_ and the :ref:`docs-code-of-conduct`.
+
+Source Code Headers
+-------------------
+Every Pigweed file containing source code must include copyright and license
+information. This includes any JS/CSS files that you might be serving out to
+browsers.
+
+Apache header for C and C++ files:
+
+.. code:: none
+
+ // Copyright 2021 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
+ // the License at
+ //
+ // https://www.apache.org/licenses/LICENSE-2.0
+ //
+ // Unless required by applicable law or agreed to in writing, software
+ // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ // License for the specific language governing permissions and limitations under
+ // the License.
+
+Apache header for Python and GN files:
+
+.. code:: none
+
+ # 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
+ # the License at
+ #
+ # https://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ # License for the specific language governing permissions and limitations under
+ # the License.
+
+Presubmit Checks and Continuous Integration
+-------------------------------------------
+All Pigweed change lists (CLs) must adhere to Pigweed's style guide and pass a
+suite of automated builds, tests, and style checks to be merged upstream. Much
+of this checking is done using Pigweed's ``pw_presubmit`` module by automated
+builders. These builders run before each Pigweed CL is submitted and in our
+continuous integration infrastructure (see `Pigweed's build console
+<https://ci.chromium.org/p/pigweed/g/pigweed/console>`_).
+
+Running Presubmit Checks
+------------------------
+To run automated presubmit checks on a pending CL, click the ``CQ DRY RUN``
+button in the Gerrit UI. The results appear in the Tryjobs section, below the
+source listing. Jobs that passed are green; jobs that failed are red.
+
+If all checks pass, you will see a ``Dry run: This CL passed the CQ dry run.``
+comment on your change. If any checks fail, you will see a ``Dry run: Failed
+builds:`` message. All failures must be addressed before submitting.
+
+In addition to the publicly visible presubmit checks, Pigweed runs internal
+presubmit checks that are only visible within Google. If any these checks fail,
+external developers will see a ``Dry run: Failed builds:`` comment on the CL,
+even if all visible checks passed. Reach out to the Pigweed team for help
+addressing these issues.
+
+Project Presubmit Checks
+------------------------
+In addition to Pigweed's presubmit checks, some projects that use Pigweed run
+their presubmit checks in Pigweed's infrastructure. This supports a development
+flow where projects automatically update their Pigweed submodule if their tests
+pass. If a project cannot build against Pigweed's tip-of-tree, it will stay on
+a fixed Pigweed revision until the issues are fixed. See the `sample project
+<https://pigweed.googlesource.com/pigweed/sample_project/>`_ for an example of
+this.
+
+Pigweed does its best to keep builds passing for dependent projects. In some
+circumstances, the Pigweed maintainers may choose to merge changes that break
+dependent projects. This will only be done if
+
+ * a feature or fix is needed urgently in Pigweed or for a different project,
+ and
+ * the project broken by the change does not imminently need Pigweed updates.
+
+The downstream project will continue to build against their last working
+revision of Pigweed until the incompatibilities are fixed.
+
+In these situations, Pigweed's commit queue submission process will fail for all
+changes. If a change passes all presubmit checks except for known failures, the
+Pigweed team may permit manual submission of the CL. Contact the Pigweed team
+for submission approval.
+
+Running local presubmits
+------------------------
+To speed up the review process, consider adding :ref:`module-pw_presubmit` as a
+git push hook using the following command:
+
+**Linux/macOS**
+
+.. code:: bash
+
+ $ pw presubmit --install
+
+This will be effectively the same as running the following command before every
+``git push``:
+
+.. code:: bash
+
+ $ pw presubmit
+
+
+.. image:: ../pw_presubmit/docs/pw_presubmit_demo.gif
+ :width: 800
+ :alt: pw presubmit demo
+
+If you ever need to bypass the presubmit hook (due to it being broken, for
+example) you may push using this command:
+
+.. code:: bash
+
+ $ git push origin HEAD:refs/for/master --no-verify
+
diff --git a/docs/getting_started.md b/docs/getting_started.md
deleted file mode 100644
index 5423d31..0000000
--- a/docs/getting_started.md
+++ /dev/null
@@ -1,334 +0,0 @@
-# Getting Started
-
-This guide will walk you through setup and general use of Pigweed.
-We hope to make the setup process as smooth as possible. If any of this doesn't
-work, please [let us know](mailto:pigweed@googlegroups.com).
-
-## Express setup
-
-If you'd like to skip the detailed explanations, 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](getting_started.md#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; Optionally, the STM32F429I-DISC1 kit to
- follow along later in the guide to run tests directly on said device(s)
-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
-$ source ./bootstrap.sh
-...
-```
-
-(3) Configure the GN build.
-
-```bash
-$ gn gen out
-Done. Made 1047 targets from 91 files in 114ms
-```
-
-(4) Start the watcher. The watcher will invoke Ninja to build all the targets
-
-```bash
-$ pw watch
-
- ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄
- ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌
- ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌
- ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌
- ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀
-
-20200707 17:24:06 INF Starting Pigweed build watcher
-20200707 17:24:06 INF Will build [1/1]: out
-20200707 17:24:06 INF Attaching filesystem watcher to $HOME/wrk/pigweed/...
-20200707 17:24:06 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 `source ./activate.sh` (or
-`activate.bat` on Windows) to re-activate the environment without
-re-bootstrapping.
-
-## Prerequisites
-
-**Linux**<br/>
-Most Linux installations should work out of box, and not require any manual
-installation of prerequisites beyond basics like `git` and `build-essential`.
-Make sure gcc is set to gcc-8.
-
-**macOS**<br/>
-To start using Pigweed on MacOS, you'll need to install XCode. Download it
-via the App Store, then install the relevant tools from the command line.
-
-```bash
-xcode-select --install
-```
-
-On macOS you may get SSL certificate errors with the system Python
-installation. Run `sudo pip install certifi` to fix this. If you get SSL
-errors with the Python from [Homebrew](https://brew.sh) try running the
-following commands to ensure Python knows how to use OpenSSL.
-
-```bash
-brew install openssl
-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](https://brew.sh), then install OpenOCD with `brew install openocd`.
-
-**Windows**<br/>
-To start using Pigweed on Windows, you'll need to install
-[Git](https://git-scm.com/download/win) and
-[Python](https://www.python.org/downloads/windows/) (2.7 or above). We recommend
-you install Git to run from the command line and third party software.
-
-If you plan to flash devices with firmware, you'll need to install OpenOCD and
-ensure it's on your system path.
-
-## Bootstrap
-
-Once you satisfied the prerequisites, you will be able to clone Pigweed and
-run the bootstrap that initializes the Pigweed virtual environment. The
-bootstrap may take several minutes to complete, so please be patient.
-
-**Linux/macOS**
-```bash
-$ git clone https://pigweed.googlesource.com/pigweed/pigweed ~/pigweed
-$ cd ~/pigweed
-$ source ./bootstrap.sh
-```
-
-**Windows**
-```batch
-:: Run git commands from the shell you set up to use with Git during install.
-> git clone https://pigweed.googlesource.com/pigweed/pigweed %HOMEPATH%\pigweed
-> cd %HOMEPATH%\pigweed
-> bootstrap.bat
-```
-
-Below is a real-time demo with roughly what you should expect to see as output:
-
-
-
-Congratulations, you are now set up to start using Pigweed!
-
-## Pigweed Environment
-
-After going through the initial setup process, your current terminal will be in
-the Pigweed development environment that provides all the tools you should need
-to develop on Pigweed. If you leave that session, you can activate the
-environment in a new session with the following command:
-
-**Linux/macOS**
-```bash
-$ source ./activate.sh
-```
-
-**Windows**
-```batch
-> activate.bat
-```
-
-Some major changes may require triggering the bootstrap again, so if you run
-into host tooling changes after a pull it may be worth re-running bootstrap.
-
-## Build Pigweed for Host
-
-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 build system.
-
-GN (Generate Ninja) just does what it says on the tin; GN generates
-[Ninja](https://ninja-build.org/) build files.
-
-The default GN configuration generates build files that allow you to build host
-binaries, device binaries, and upstream documentation all in one Ninja
-invocation.
-
-Run GN as seen below:
-
-```bash
-$ gn gen out
-```
-
-Note that `out` is simply the directory the build files are saved to. Unless
-this directory is deleted or you desire to do a clean build, there's no need to
-run GN again; just rebuild using Ninja directly.
-
-Now that we have build files, it's time to build Pigweed!
-
-Now you *could* manually invoke the host build using `ninja -C out` every
-time you make a change, but that's tedious. Instead, let's use `pw_watch`.
-
-Go ahead and start `pw_watch`:
-
-```bash
-$ pw watch
-```
-
-When `pw_watch` starts up, it will automatically build the directory we
-generated in `out`. Additionally, `pw_watch` watches source code files for
-changes, and triggers a Ninja build whenever it notices a file has been saved.
-You might be surprised how much time it can save you!
-
-With `pw watch` running, try modifying `pw_status/public/pw_status/status.h` and
-watch the build re-trigger when you save the file.
-
-See below for a demo of this in action:
-
-
-
-## Running Unit Tests
-
-Fun fact, you've been running the unit tests already! Ninja builds targeting the
-host automatically build and run the unit tests. Unit tests err on the side of
-being quiet in the success case, and only output test results when there's a
-failure.
-
-To see the a test failure, you can modify `pw_status/status_test.cc` to fail
-by changing one of the strings in the "KnownString" test.
-
-
-
-Running tests as part of the build isn't particularly expensive because GN
-caches passing tests. Each time you build, only the tests that are affected
-(whether directly or transitively) by the code changes since the last build will
-be re-built and re-run.
-
-Try running the `pw_status` test manually:
-```bash
-$ ./out/host_{clang,gcc}_debug/obj/pw_status/test/status_test
-```
-
-Depending on your host OS, the compiler will default to either `clang` or `gcc`.
-
-## Building for a Device
-
-A Pigweed "target" is a build configuration that includes a toolchain, default
-library configurations, and more to result in binaries that run natively on the
-target. With the default build invocation, you're already building for a device
-target (the STMicroelectronics STM32F429I-DISC1) in parallel with the host
-build!
-
-If you want to build JUST for the device, you can kick of watch with:
-
-```bash
-$ pw watch stm32f429i
-```
-
-This is equivalent to the following Ninja invocation:
-
-```bash
-$ ninja -C out stm32f429i
-```
-
-
-## Running Tests on a Device
-
-While tests run automatically on the host, it takes a few more steps to get
-tests to run automatically on a device, too. Even though we've verified tests
-pass on the host, it's crucial to verify the same with on-device testing. We've
-encountered some unexpected bugs that can only be found by running the unit
-tests directly on the device.
-
-### 1. Connect Device(s)
-Connect any number of STM32F429I-DISC1 boards to your computer using the mini
-USB port on the board (**not** the micro USB). Pigweed will automatically detect
-the boards and distribute the tests across the devices. More boards = faster
-tests! Keep in mind that you may have to make some environment specific updates
-to ensure you have permissions to use the USB device. For example, on Linux you
-may need to update your udev rules and ensure you're in the plugdev and dialout
-groups.
-
-
-
-### 2. Launch Test Server
-To allow Ninja to run tests on an arbitrary number of devices, Ninja will send
-test requests to a server running in the background. Launch the server in
-another window using the command below (remember, you'll need to activate the
-Pigweed environment first).
-
-```shell
- $ stm32f429i_disc1_test_server
-```
-
-**Note:** If you attach or detach any more boards to your workstation you'll
-need to relaunch this server.
-
-### 3. Configure GN
-
-We can tell GN to use the testing server by enabling a build arg specific to
-the stm32f429i-disc1 target.
-
-```shell
-$ gn args out
-# Append this line to the file that opens in your editor to tell GN to run
-# on-device unit tests.
-pw_use_test_server = true
-```
-
-### Done!
-
-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:
-
-
-
-## Building the Documentation
-
-In addition to the markdown documentation, Pigweed has a collection of
-information-rich RST files that are used to generate HTML documentation. All the
-docs are hosted at https://pigweed.dev/, and are built as a part of the default
-build invocation. This makes it easier to make changes and see how they turn
-out. Once built, you can find the rendered HTML documentation at
-`out/docs/gen/docs/html`.
-
-You can explicitly build just the documentation with the command below.
-
-```shell
-$ ninja -C out docs
-```
-
-## Next steps
-
-This concludes the introduction to developing with Pigweed. If you'd like to see
-more of what Pigweed has to offer, feel free to dive into the per-module
-documentation. If you run into snags along the way, please [let us
-know](mailto:pigweed@googlegroups.com)!
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
new file mode 100644
index 0000000..dd00eaa
--- /dev/null
+++ b/docs/getting_started.rst
@@ -0,0 +1,401 @@
+.. _docs-getting-started:
+
+===============
+Getting Started
+===============
+This guide will walk you through the typical upstream development workflow.
+
+.. note::
+
+ We don't yet have thorough documentation for leveraging Pigweed in a separate
+ project (our intended use case!). The `sample project
+ <https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/master/README.md>`_
+ shows how to use Pigweed as a library in your broader project, but you may
+ need further guidance.
+
+ We're happy to help you get your project setup; just drop in our `chat room
+ <https://discord.gg/M9NSeTA>`_ or send a note to the `mailing list
+ <https://groups.google.com/forum/#!forum/pigweed>`_.
+
+Express setup
+=============
+If you'd like to skip the detailed explanations, 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 :ref:`prerequisites`. The express setup
+configures Pigweed's watcher for three targets to give a taste of Pigweed:
+
+#. **Host** - Mac, Linux, or Windows. Builds and runs tests
+#. **Device/STM32F429** - Build only; Optionally, the STM32F429I-DISC1 kit to
+ follow along later in the guide to run tests directly on said device(s)
+#. **Docs** - Builds the Pigweed docs
+
+To get setup:
+
+#. Make sure you have Git and Python installed and on your path.
+
+#. Clone Pigweed and bootstrap the environment (compiler setup & more). **Be
+ patient, this step downloads ~1GB of LLVM, GCC, and other tooling**.
+
+ .. code:: bash
+
+ $ cd ~
+ $ git clone https://pigweed.googlesource.com/pigweed/pigweed
+ ...
+ $ cd pigweed
+ $ source ./bootstrap.sh (On Linux & Mac)
+ $ bootstrap.bat (On Windows)
+ ...
+
+#. Configure the GN build.
+
+ .. code:: bash
+
+ $ gn gen out
+ Done. Made 1047 targets from 91 files in 114ms
+
+#. Start the watcher. The watcher will invoke Ninja to build all the targets
+
+ .. code:: bash
+
+ $ pw watch
+
+ ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄
+ ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌
+ ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌
+ ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌
+ ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀
+
+ 20200707 17:24:06 INF Starting Pigweed build watcher
+ 20200707 17:24:06 INF Will build [1/1]: out
+ 20200707 17:24:06 INF Attaching filesystem watcher to $HOME/wrk/pigweed/...
+ 20200707 17:24:06 INF Triggering initial build...
+ ...
+
+#. **Congratulations, you're ready to go!** Now take Pigweed for a spin by
+ making a test fail.
+
+#. 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.
+
+#. Save the file. Observe the watcher rebuild & retest, and fail. Restore the
+ test if you feel like it.
+
+#. Open the generated docs in ``out/docs/gen/docs/html/index.html`` in your
+ browser.
+
+#. Edit ``docs/getting_started.rst`` (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 ``source ./activate.sh`` (or
+``activate.bat`` on Windows) to re-activate the environment without
+re-bootstrapping.
+
+.. _prerequisites:
+
+Prerequisites
+-------------
+**Linux**
+
+Most Linux installations should work out of box, and not require any manual
+installation of prerequisites beyond basics like ``git`` and
+``build-essential``. Make sure gcc is set to gcc-8.
+
+**macOS**
+
+To start using Pigweed on MacOS, you'll need to install XCode. Download it
+via the App Store, then install the relevant tools from the command line.
+
+.. code:: none
+
+ $ xcode-select --install
+
+On macOS you may get SSL certificate errors with the system Python
+installation. Run ``sudo pip install certifi`` to fix this. If you get SSL
+errors with the Python from `Homebrew <https://brew.sh>`_ try running the
+following commands to ensure Python knows how to use OpenSSL.
+
+.. code:: none
+
+ $ brew install openssl
+ $ 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](https://brew.sh), then install OpenOCD with `brew install openocd`.
+
+**Windows**
+
+To start using Pigweed on Windows, you'll need to install `Git
+<https://git-scm.com/download/win>`_ and `Python
+<https://www.python.org/downloads/windows/>`_. We recommend you install Git to
+run from the command line and third party software.
+
+If you plan to flash devices with firmware, you'll need to install OpenOCD and
+ensure it's on your system path.
+
+Bootstrap
+=========
+
+Once you satisfied the prerequisites, you will be able to clone Pigweed and
+run the bootstrap that initializes the Pigweed virtual environment. The
+bootstrap may take several minutes to complete, so please be patient.
+
+**Linux & macOS**
+
+.. code:: bash
+
+ $ git clone https://pigweed.googlesource.com/pigweed/pigweed ~/pigweed
+ $ cd ~/pigweed
+ $ source ./bootstrap.sh
+
+**Windows**
+
+.. code:: batch
+
+ :: Run git commands from the shell you set up to use with Git during install.
+ > git clone https://pigweed.googlesource.com/pigweed/pigweed %HOMEPATH%\pigweed
+ > cd %HOMEPATH%\pigweed
+ > bootstrap.bat
+
+Below is a real-time demo with roughly what you should expect to see as output:
+
+.. image:: images/pw_env_setup_demo.gif
+ :width: 800
+ :alt: build example using pw watch
+
+Congratulations, you are now set up to start using Pigweed!
+
+Pigweed Environment
+===================
+After going through the initial setup process, your current terminal will be in
+the Pigweed development environment that provides all the tools you should need
+to develop on Pigweed. If you leave that session, you can activate the
+environment in a new session with the following command:
+
+**Linux & macOS**
+
+.. code:: bash
+
+ $ source ./activate.sh
+
+**Windows**
+
+.. code:: batch
+
+ > activate.bat
+
+Some major changes may require triggering the bootstrap again, so if you run
+into host tooling changes after a pull it may be worth re-running bootstrap.
+
+Build Pigweed for Host
+======================
+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 build system.
+
+GN (Generate Ninja) just does what it says on the tin; GN generates
+`Ninja <https://ninja-build.org/>`_ build files.
+
+The default GN configuration generates build files that allow you to build host
+binaries, device binaries, and upstream documentation all in one Ninja
+invocation.
+
+Run GN as seen below:
+
+.. code:: bash
+
+ $ gn gen out
+
+Note that ``out`` is simply the directory the build files are saved to. Unless
+this directory is deleted or you desire to do a clean build, there's no need to
+run GN again; just rebuild using Ninja directly.
+
+Now that we have build files, it's time to build Pigweed!
+
+Now you *could* manually invoke the host build using ``ninja -C out`` every
+time you make a change, but that's tedious. Instead, let's use ``pw_watch``.
+
+Go ahead and start ``pw_watch``:
+
+.. code:: bash
+
+ $ pw watch
+
+When ``pw_watch`` starts up, it will automatically build the directory we
+generated in ``out``. Additionally, ``pw_watch`` watches source code files for
+changes, and triggers a Ninja build whenever it notices a file has been saved.
+You might be surprised how much time it can save you!
+
+With ``pw watch`` running, try modifying
+``pw_status/public/pw_status/status.h`` and watch the build re-trigger when you
+save the file.
+
+See below for a demo of this in action:
+
+.. image:: images/pw_watch_build_demo.gif
+ :width: 800
+ :alt: build example using pw watch
+
+Running Unit Tests
+==================
+Fun fact, you've been running the unit tests already! Ninja builds targeting
+the host automatically build and run the unit tests. Unit tests err on the side
+of being quiet in the success case, and only output test results when there's a
+failure.
+
+To see the a test failure, modify ``pw_status/status_test.cc`` to fail by
+changing one of the strings in the "KnownString" test.
+
+.. image:: images/pw_watch_test_demo.gif
+ :width: 800
+ :alt: example test failure using pw watch
+
+Running tests as part of the build isn't particularly expensive because GN
+caches passing tests. Each time you build, only the tests that are affected
+(whether directly or transitively) by the code changes since the last build
+will be re-built and re-run.
+
+Try running the ``pw_status`` test manually:
+
+.. code:: bash
+
+ $ ./out/host_{clang,gcc}_debug/obj/pw_status/test/status_test
+
+Depending on your host OS, the compiler will default to either ``clang`` or
+``gcc``.
+
+Building for a Device
+=====================
+A Pigweed "target" is a build configuration that includes a toolchain, default
+library configurations, and more to result in binaries that run natively on the
+target. With the default build invocation, you're already building for a device
+target (the STMicroelectronics STM32F429I-DISC1) in parallel with the host
+build!
+
+If you want to build JUST for the device, you can kick of watch with:
+
+.. code:: bash
+
+ $ pw watch stm32f429i
+
+This is equivalent to the following Ninja invocation:
+
+.. code:: bash
+
+ $ ninja -C out stm32f429i
+
+Running Tests on a Device
+=========================
+While tests run automatically on the host, it takes a few more steps to get
+tests to run automatically on a device, too. Even though we've verified tests
+pass on the host, it's crucial to verify the same with on-device testing. We've
+encountered some unexpected bugs that can only be found by running the unit
+tests directly on the device.
+
+1. Connect Device(s)
+--------------------
+Connect any number of STM32F429I-DISC1 boards to your computer using the mini
+USB port on the board (**not** the micro USB). Pigweed will automatically
+detect the boards and distribute the tests across the devices. More boards =
+faster tests! Keep in mind that you may have to make some environment specific
+updates to ensure you have permissions to use the USB device. For example, on
+Linux you may need to update your udev rules and ensure you're in the plugdev
+and dialout groups.
+
+.. image:: images/stm32f429i-disc1_connected.jpg
+ :width: 800
+ :alt: development boards connected via USB
+
+2. Launch Test Server
+---------------------
+To allow Ninja to run tests on an arbitrary number of devices, Ninja will send
+test requests to a server running in the background. Launch the server in
+another window using the command below (remember, you'll need to activate the
+Pigweed environment first).
+
+.. code:: bash
+
+ $ stm32f429i_disc1_test_server
+
+**Note:** If you attach or detach any more boards to your workstation you'll
+need to relaunch this server.
+
+3. Configure GN
+---------------
+Tell GN to use the testing server by enabling a build arg specific to the
+stm32f429i-disc1 target.
+
+.. code:: bash
+
+ $ gn args out
+ # Append this line to the file that opens in your editor to tell GN to run
+ # on-device unit tests.
+ pw_use_test_server = true
+
+Done!
+-----
+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:
+
+.. image:: images/pw_watch_on_device_demo.gif
+ :width: 800
+ :alt: pw watch running on-device tests
+
+Building the Documentation
+==========================
+In addition to the markdown documentation, Pigweed has a collection of
+information-rich RST files that are used to generate HTML documentation. All
+the docs are hosted at https://pigweed.dev/, and are built as a part of the
+default build invocation. This makes it easier to make changes and see how they
+turn out. Once built, you can find the rendered HTML documentation at
+``out/docs/gen/docs/html``.
+
+You can explicitly build just the documentation with the command below.
+
+.. code:: bash
+
+ $ ninja -C out docs
+
+This concludes the introduction to developing for upstream Pigweed.
+
+Next steps
+==========
+
+Check out other modules
+-----------------------
+If you'd like to see more of what Pigweed has to offer, dive into the
+:ref:`docs-module-guides`.
+
+Check out the sample project
+----------------------------
+We have a `sample project
+<https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/master/README.md>`_
+that demonstrates how to use Pigweed in your own project. Note that there are
+many ways to leverage Pigweed and the sample project is one approach.
+
+Check out the Hackaday Supercon talk about Pigweed
+--------------------------------------------------
+We gave a talk at Hackaday's 2021 supercon, `Give Pigweed a Whirl
+<https://hackaday.com/2021/01/13/remoticon-video-pigweed-brings-embedded-unit-testing-library-integration-to-commandline/>`_
+
+We've made improvements since we gave the talk; for example, we now have RTOS
+primitives.
+
+Set up Pigweed for your own project
+------------------------------------
+We don't yet have thorough documentation for leveraging Pigweed in a separate
+project (our intended use case!). The `sample project
+<https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/master/README.md>`_
+shows how to use Pigweed as a library in your broader project, but you may need
+further guidance.
+
+Dropping into our `chat room <https://discord.gg/M9NSeTA>`_ is the most
+immediate way to get help. Alternatively, you can send a note to the `mailing
+list <https://groups.google.com/forum/#!forum/pigweed>`_.
diff --git a/docs/index.rst b/docs/index.rst
index de7c142..8d996e4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,20 +1,18 @@
.. highlight:: sh
-.. mdinclude:: README.md
-
.. toctree::
:maxdepth: 1
:hidden:
Home <self>
- docs/getting_started.md
+ docs/getting_started
Source Code <https://cs.opensource.google/pigweed/pigweed>
Code Reviews <https://pigweed-review.googlesource.com>
Mailing List <https://groups.google.com/forum/#!forum/pigweed>
Chat Room <https://discord.gg/M9NSeTA>
Issue Tracker <https://bugs.pigweed.dev/>
- CONTRIBUTING.md
- CODE_OF_CONDUCT.md
+ docs/contributing
+ docs/code_of_conduct
docs/embedded_cpp_guide
Code Style <docs/style_guide>
targets
@@ -22,3 +20,147 @@
FAQ <docs/faq>
docs/module_structure
module_guides
+
+=======
+Pigweed
+=======
+Pigweed is an open source collection of embedded-targeted libraries--or as we
+like to call them, modules. These modules are building blocks and
+infrastructure that enable faster and more reliable development on
+small-footprint MMU-less 32-bit microcontrollers like the STMicroelectronics
+STM32L452 or the Nordic nRF52832.
+
+.. attention::
+
+ Pigweed is in **early access**; though many modules are shipping in
+ production already. If you're interested in using Pigweed, please reach out
+ in our `chat room <https://discord.gg/M9NSeTA>`_ or on the `mailing list
+ <https://groups.google.com/forum/#!forum/pigweed>`_.
+
+Getting Started
+---------------
+If you'd like to get set up with Pigweed, please visit the
+:ref:`docs-getting-started` guide.
+
+What does Pigweed offer?
+------------------------
+There are many modules in Pigweed; this section showcases a selection that
+produce visual output. For more information about the different Pigweed module
+offerings, refer to :ref:`docs-module-guides` section.
+
+``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 the embedded space, file system watchers are less prevalent;
+however, they are no less useful! The Pigweed watcher module makes it easy to
+instantly compile, flash, and run tests upon save. Combined with the GN-based
+build which expresses the full dependency tree, only the exact tests affected
+by a file change are run on saves.
+
+The demo below shows `pw_watch <module-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.
+
+.. image:: docs/images/pw_watch_on_device_demo.gif
+ :width: 800
+ :alt: pw watch running on-device tests
+
+``pw_presubmit`` - Vacuum 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-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.
+
+.. image:: pw_presubmit/docs/pw_presubmit_demo.gif
+ :width: 800
+ :alt: pw presubmit demo
+
+``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**. An entire suite of tools is needed
+for building non-trivial production embedded projects, and need to be
+installed. For example:
+
+- A C++ compiler for your target device, and also for your host
+- A build system or three; for example, GN, Ninja, CMake, Bazel
+- A code formatting program like clang-format
+- A debugger like OpenOCD to flash and debug your embedded device
+- A known Python version with known modules installed for scripting
+- A Go compiler for the Go-based command line tools
+- ... and so on
+
+In the server space, container solutions like Docker or Podman solve this;
+however, container solutions are a mixed bag for embedded systems development
+where one frequently needs access to native system resources like USB devices,
+or must operate on Windows.
+
+`pw_env_setup <module-pw_env_setup>`_ is our compromise solution for this
+problem that works on Mac, Windows, and Linux. It leverages the Chrome
+Infrastructure Packaging Deployment 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
+tooling is designed to be reused by any project.
+
+.. image:: docs/images/pw_env_setup_demo.gif
+ :width: 800
+ :alt: pw environment setup demo
+
+``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 <module-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.
+
+.. image:: docs/images/pw_status_test.png
+ :width: 800
+ :alt: pw_status test run natively on host
+
+And more!
+---------
+Here is a selection of interesting modules:
+
+ - :ref:`module-pw_cpu_exception_cortex_m` - 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!
+
+ - :ref:`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.
+
+ - :ref:`module-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.
+
+ - :ref:`module-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.
+
+ - :ref:`module-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.
+
+See the :ref:`docs-module-guides` for the complete list of modules and their
+documentation.
