docs: Refactor the getting started section
There should be a getting started homepage that lists all the
various paths for getting started with Pigweed. Also, we're
preparing for a Bazel-focused getting started path.
Change-Id: I4b7e1829b3024f72db6da07c3bc8bd6b4df90205
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/176331
Reviewed-by: Ted Pudlik <tpudlik@google.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Commit-Queue: Kayce Basques <kayce@google.com>
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 24e4739..95ff3dd 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -55,7 +55,8 @@
"editors.rst",
"embedded_cpp_guide.rst",
"faq.rst",
- "getting_started.rst",
+ "get_started/index.rst",
+ "get_started/upstream.rst",
"infra/ci_cq_intro.rst",
"infra/index.rst",
"infra/rollers.rst",
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 83282be..749304a 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -122,7 +122,7 @@
Building
^^^^^^^^
To build the documentation, follow the :ref:`getting
-started<docs-getting-started>` guide so you can build Pigweed. Then:
+started<docs-get-started-upstream>` guide so you can build Pigweed. Then:
#. Change to your checkout directory and ``. activate.sh`` if necessary
#. Run ``pw watch out`` to build the code, run tests, and build docs
diff --git a/docs/get_started/index.rst b/docs/get_started/index.rst
new file mode 100644
index 0000000..3048b47
--- /dev/null
+++ b/docs/get_started/index.rst
@@ -0,0 +1,40 @@
+.. _docs-get-started:
+
+===========
+Get Started
+===========
+Stay tuned for a tutorial on getting started with Pigweed in a Bazel-based project,
+:ref:`Pigweed's primary build system <seed-0111>` going forward.
+
+.. grid:: 2
+
+ .. grid-item-card:: :octicon:`code` Sample Project
+ :link: https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md
+ :link-type: url
+ :class-item: sales-pitch-cta-primary
+
+ Fork the Sample Project, a repository that outlines the recommended way to use
+ Pigweed in a broader GN-based project.
+
+ .. grid-item-card:: :octicon:`code` Kudzu
+ :link: docs-kudzu
+ :link-type: ref
+ :class-item: sales-pitch-cta-secondary
+
+ Study the code of Kudzu, a just-for-fun Maker Faire 2023 project that
+ demonstrates complex Pigweed usage.
+
+.. grid:: 2
+
+ .. grid-item-card:: :octicon:`list-ordered` Upstream Pigweed
+ :link: docs-get-started-upstream
+ :link-type: ref
+ :class-item: sales-pitch-cta-secondary
+
+ Get set up to contribute to upstream Pigweed.
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+
+ Upstream Pigweed <upstream>
diff --git a/docs/getting_started.rst b/docs/get_started/upstream.rst
similarity index 96%
rename from docs/getting_started.rst
rename to docs/get_started/upstream.rst
index 42f85dd..9cf2d74 100644
--- a/docs/getting_started.rst
+++ b/docs/get_started/upstream.rst
@@ -1,8 +1,8 @@
-.. _docs-getting-started:
+.. _docs-get-started-upstream:
-===============
-Getting Started
-===============
+=============================================
+Get Started With Upstream Pigweed Development
+=============================================
This guide will walk you through the typical upstream development workflow.
.. note::
@@ -174,7 +174,7 @@
Below is a real-time demo with roughly what you should expect to see as output:
-.. image:: images/pw_env_setup_demo.gif
+.. image:: ../images/pw_env_setup_demo.gif
:width: 800
:alt: build example using pw watch
@@ -260,7 +260,7 @@
See below for a demo of this in action:
-.. image:: images/pw_watch_build_demo.gif
+.. image:: ../images/pw_watch_build_demo.gif
:width: 800
:alt: build example using pw watch
@@ -274,7 +274,7 @@
To see 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
+.. image:: ../images/pw_watch_test_demo.gif
:width: 800
:alt: example test failure using pw watch
@@ -330,7 +330,7 @@
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
+.. image:: ../images/stm32f429i-disc1_connected.jpg
:width: 800
:alt: development boards connected via USB
@@ -367,7 +367,7 @@
See the demo below for an example of what this all looks like put together:
-.. image:: images/pw_watch_on_device_demo.gif
+.. image:: ../images/pw_watch_on_device_demo.gif
:width: 800
:alt: pw watch running on-device tests
diff --git a/docs/index.rst b/docs/index.rst
index a71f166..95c13dc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,7 @@
:hidden:
Home <self>
- docs/getting_started
+ docs/get_started/index
docs/concepts/index
targets
Modules <module_guides>
@@ -70,7 +70,7 @@
Check out `Pigweed Sample Project <https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md>`_
to see how to use Pigweed as a library in your broader project.
-Visit the :ref:`docs-getting-started` guide to learn how to bootstrap and
+Visit the :ref:`docs-get-started-upstream` guide to learn how to bootstrap and
activate a Pigweed environment, build Pigweed for a specific host or device,
run tests, and more.
diff --git a/pw_build/gn.rst b/pw_build/gn.rst
index be4567f..d3ffc39 100644
--- a/pw_build/gn.rst
+++ b/pw_build/gn.rst
@@ -13,7 +13,7 @@
Building upstream Pigweed
-------------------------
-See Pigweed's :ref:`docs-getting-started` guide for a high-level introduction
+See Pigweed's :ref:`docs-get-started-upstream` guide for a high-level introduction
to using the GN build.
Pigweed's root ``BUILD.gn`` file contains a variety of groups to help you
diff --git a/seed/0001-the-seed-process.rst b/seed/0001-the-seed-process.rst
index c7e340f..0ec702b 100644
--- a/seed/0001-the-seed-process.rst
+++ b/seed/0001-the-seed-process.rst
@@ -91,7 +91,7 @@
Suppose you'd like to propose a new Pigweed RPC Over Smoke Signals protocol.
#. If you haven't already, clone the Pigweed repository and set it up locally,
- following the :ref:`docs-getting-started` guide.
+ following the :ref:`docs-get-started-upstream` guide.
#. Claim a number for your SEED. This should be the next sequential number
listed within the `SEED index`_'s ``toctree`` table. (We will use 5309 for
