docs: add cross-references for improved navigation (Phase 4)

Add "Next Steps" and "See Also" sections to key pages to help users
discover related content and navigate naturally between topics.

Changes:
- Enhanced quickstart.rst with categorized next steps (Learn More,
  Common Tasks, Customize Builds)
- Added next steps to getting-started.rst linking to containers,
  constraints, customization, and concepts
- Added "See Also" section to customization.md with links to reference
  docs and related how-tos
- Added "See Also" section to using.md with links to concepts and
  how-to guides
- Enhanced concepts/index.rst with overview, related guides, and
  reference links

Impact: Users can naturally flow from one topic to related topics

Related: #969

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dhellmann

docs/concepts/index.rst

@@ -1,8 +1,34 @@
 Concepts
 ========
 
+Understanding how fromager works under the hood.
+
+Key Topics
+----------
+
+These guides explain the fundamental concepts and design principles behind fromager:
+
+* **Bootstrap vs Build Modes** - Understand the difference between recursive discovery (bootstrap) and single-package builds (build)
+* **Dependency Types** - Learn about build-system, build-backend, build-sdist, and install dependencies
+
 .. toctree::
    :maxdepth: 1
 
    bootstrap-vs-build
    dependencies
+
+Related Practical Guides
+-------------------------
+
+Apply these concepts with task-oriented guides:
+
+* :doc:`/using` - Bootstrap and build mode usage
+* :doc:`/how-tos/repeatable-builds` - Use build graphs for consistent builds
+* :doc:`/how-tos/graph-commands/index` - Analyze dependency graphs
+* :doc:`/customization` - Customize the build process
+
+Reference Material
+------------------
+
+* :doc:`/reference/glossary` - Definitions of key terms
+* :doc:`/reference/files` - Build order and graph file formats

docs/customization.md

@@ -474,3 +474,22 @@ def mycommand(
 ) -> None:
     ...
 ```
+
+## See Also
+
+**Reference Documentation:**
+
+* [Configuration Reference](reference/config-reference.rst) - Complete settings schema
+* [Hooks Reference](reference/hooks.rst) - Override plugin documentation
+* [CLI Reference](reference/cli.rst) - Command-line options
+
+**How-To Guides:**
+
+* [Override pyproject.toml](how-tos/pyproject-overrides.rst) - Modify build configuration
+* [Build from Git](how-tos/build-from-git-repo.rst) - Use custom source repositories
+* [Multiple Versions](how-tos/multiple-versions.rst) - Handle version conflicts
+
+**Concepts:**
+
+* [Bootstrap vs Build](concepts/bootstrap-vs-build.rst) - Understand build modes
+* [Dependencies](concepts/dependencies.rst) - Dependency types and resolution

docs/getting-started.rst

@@ -118,3 +118,24 @@ The output below is redacted for brevity. Missing sections are replaced with ``.
 As each dependency is built, fromager will show output from the build process
 and progress information. At the end of the build, fromager shows the list of
 packages that were built and how long each step took.
+
+Next Steps
+----------
+
+Now that you understand the basic workflow and debugging process:
+
+**Improve Your Workflow:**
+
+* :doc:`how-tos/containers` - Run builds in containers for better isolation
+* :doc:`how-tos/bootstrap-constraints` - Pin versions for reproducible builds
+* :doc:`how-tos/repeatable-builds` - Use previous build graphs for consistency
+
+**Customize Builds:**
+
+* :doc:`customization` - Add patches, override settings, configure variants
+* :doc:`how-tos/pyproject-overrides` - Override pyproject.toml settings
+
+**Learn How It Works:**
+
+* :doc:`concepts/index` - Understand bootstrap mode, build isolation, and more
+* :doc:`reference/glossary` - Definitions of key terms

docs/quickstart.rst

@@ -76,8 +76,21 @@ The ``-c`` option ensures fromager uses exactly the versions you specify.
 Next Steps
 ----------
 
-Now that you've seen fromager work with a simple package, you might want to:
+Now that you've seen fromager work with a simple package, explore:
 
-* Learn to debug build failures with a more complex example in :doc:`getting-started`
-* Customize builds with settings, patches, and variants in :doc:`customization`
-* Check specific guides in :doc:`how-tos/index`
+**Learn More:**
+
+* :doc:`getting-started` - Detailed walkthrough with debugging examples
+* :doc:`concepts/index` - Understand how fromager works
+
+**Common Tasks:**
+
+* :doc:`how-tos/containers` - Run fromager in containers (recommended)
+* :doc:`how-tos/bootstrap-constraints` - Pin versions for reproducible builds
+* :doc:`how-tos/repeatable-builds` - Ensure consistent builds across environments
+
+**Customize Builds:**
+
+* :doc:`customization` - Comprehensive customization guide
+* :doc:`reference/config-reference` - Configuration reference
+* :doc:`how-tos/index` - Task-oriented guides

docs/using.md

@@ -252,3 +252,22 @@ The `step build-wheel` command creates a wheel using the build
 environment and prepared source, compiling any extensions using the
 appropriate override environment settings (refer to
 [customization](customization.md) for details about overrides).
+
+## See Also
+
+**Understanding Build Modes:**
+
+* [Bootstrap vs Build](concepts/bootstrap-vs-build.rst) - Detailed comparison of build modes
+* [Dependencies](concepts/dependencies.rst) - How dependency resolution works
+
+**How-To Guides:**
+
+* [Bootstrap with Constraints](how-tos/bootstrap-constraints.rst) - Pin versions for reproducible builds
+* [Repeatable Builds](how-tos/repeatable-builds.rst) - Use build graphs for consistency
+* [Parallel Builds](how-tos/parallel.rst) - Speed up builds with parallelization
+* [Build Web Server](how-tos/build-web-server.rst) - Serve built packages
+
+**Reference:**
+
+* [CLI Reference](reference/cli.rst) - Complete command documentation
+* [Files Reference](reference/files.md) - Build order and graph file formats