docs: create reference section and reorganize main index (Phase 1)

Create dedicated reference documentation section to improve discoverability
of CLI, configuration, and file format documentation.

Changes:
- Create docs/reference/ directory with landing page
- Move reference files: cli.rst, config-reference.rst, hooks.rst,
  files.md, glossary.rst to reference/
- Reorganize main index with clear Diátaxis framework sections:
  * Getting Started (quickstart, getting-started)
  * Guides (how-tos, customization, using)
  * Concepts & Explanation (concepts, http-retry)
  * Reference (new reference section)
  * Development (develop)
- Update all cross-references to moved files
- Add Quick Reference section to reference/index.rst for common lookups

Impact: Reference material now discoverable in ≤2 clicks from main index

Related: #969

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

Author: dhellmann

docs/conf.py

@@ -58,7 +58,7 @@
 # sphinxcontrib.spelling settings
 # File references a function object. Spell checker complaints about typo in
 # random object id.
-spelling_exclude_patterns = ["config-reference.rst"]
+spelling_exclude_patterns = ["reference/config-reference.rst"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/customization.md

@@ -323,7 +323,7 @@ requires = ["setuptools>=68.0.0", "torch", "triton"]
 
 ## Override plugins
 
-Override plugins are documented in [the reference guide](hooks.rst).
+Override plugins are documented in [the reference guide](reference/hooks.rst).
 
 ## Canonical distribution names
 

docs/index.rst

@@ -23,21 +23,58 @@ behavior that works for most PEP-517 compatible packages, but support
 overriding all of the actions for special cases, without encoding
 those special cases directly into fromager.
 
+Getting Started
+---------------
+
+Quick introduction and detailed walkthrough for new users.
+
 .. toctree::
    :maxdepth: 2
 
    quickstart.rst
-   using.md
    getting-started.rst
+
+Guides
+------
+
+Task-oriented guides for common workflows and customization.
+
+.. toctree::
+   :maxdepth: 2
+
+   how-tos/index.rst
    customization.md
+   using.md
+
+Concepts & Explanation
+----------------------
+
+Understanding how fromager works and technical deep-dives.
+
+.. toctree::
+   :maxdepth: 2
+
    concepts/index.rst
-   how-tos/index.rst
-   hooks.rst
-   files.md
    http-retry.md
-   config-reference.rst
-   cli.rst
-   glossary.rst
+
+Reference
+---------
+
+Technical reference for CLI, configuration, files, and terminology.
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/index.rst
+
+Development
+-----------
+
+Contributing to fromager.
+
+.. toctree::
+   :maxdepth: 2
+
    develop.md
 
 What's with the name?

docs/quickstart.rst

@@ -59,7 +59,7 @@ figured out the build and runtime dependencies, built each package in the
 correct order, and created wheels in ``wheels-repo/downloads/``.
 
 For a detailed explanation of the output files and directories, see
-:doc:`files`.
+:doc:`reference/files`.
 
 Pinning Versions with Constraints
 ---------------------------------

docs/cli.rst docs/reference/cli.rstdocs/cli.rst renamed to docs/reference/cli.rst

@@ -40,7 +40,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       The sequence in which packages must be built, determined by analyzing the
       :term:`dependency graph`. Packages are ordered bottom-up (topological sort)
       so that each package's dependencies are built before the package itself.
-      Stored in ``build-order.json``. See :doc:`/files` for the file format.
+      Stored in ``build-order.json``. See :doc:`/reference/files` for the file format.
 
    build sequence
       A command (``build-sequence``) that processes a pre-determined :term:`build order`
@@ -94,7 +94,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       Version specifications that control package :term:`resolution`. Provided via a
       ``constraints.txt`` file, they ensure specific versions are used or avoided
       during builds. Unlike :term:`requirements <requirement>`, constraints only
-      apply when a package is already needed. See :doc:`/files` for format details.
+      apply when a package is already needed. See :doc:`/reference/files` for format details.
 
    cyclic dependency
       A circular dependency where packages depend on each other, forming a loop
@@ -112,7 +112,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       A directed graph representing all packages and their relationships discovered
       during :term:`bootstrap`. Nodes represent resolved package versions, and edges
       capture the :term:`requirement` specifications and dependency types (toplevel,
-      install, build-system, etc.). Stored in ``graph.json``. See :doc:`/files` and
+      install, build-system, etc.). Stored in ``graph.json``. See :doc:`/reference/files` and
       :doc:`/how-tos/graph-commands/index`.
 
    distribution name
@@ -124,7 +124,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       An extension point in fromager that allows customization of specific
       operations. Hooks include ``post_build``, ``prebuilt_wheel``, and
       ``post_bootstrap``. Multiple plugins can register for the same hook.
-      See :doc:`/hooks` and :doc:`/customization`.
+      See :doc:`/reference/hooks` and :doc:`/customization`.
 
    install dependency
       A runtime dependency of a package, extracted from the built :term:`wheel`'s
@@ -153,7 +153,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       A Python module registered as an entry point that provides custom implementations
       of fromager operations for specific packages. Unlike :term:`hooks <hook>`, overrides
       replace the default behavior entirely. Plugins can customize source acquisition,
-      dependency resolution, building, and more. See :doc:`/hooks`.
+      dependency resolution, building, and more. See :doc:`/reference/hooks`.
 
    package index
       A server providing package metadata and downloads, following the
@@ -234,7 +234,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       A strategy class that supplies version :term:`candidates <candidate>` during
       :term:`resolution`. The default provider queries :term:`PyPI`, but custom
       providers can resolve versions from GitHub tags, GitLab tags, or other sources.
-      See :doc:`/hooks`.
+      See :doc:`/reference/hooks`.
 
    sdist-only mode
       A :term:`bootstrap` mode (``--sdist-only``) that builds :term:`source
@@ -246,7 +246,7 @@ This glossary defines key terms used throughout Fromager's documentation and cod
       Configuration options that customize package building. Can be global (in
       ``overrides/settings.yaml``) or per-package (in ``overrides/settings/<name>.yaml``).
       Settings control environment variables, source URLs, :term:`variants <variant>`,
-      and more. See :doc:`/customization` and :doc:`/config-reference`.
+      and more. See :doc:`/customization` and :doc:`/reference/config-reference`.
 
    Simple API
       The :pep:`503` specification for :term:`package index` directory layout.
@@ -299,4 +299,4 @@ This glossary defines key terms used throughout Fromager's documentation and cod
    work directory
       The directory (default: ``work-dir/``) where fromager stores working files
       during builds. Contains :term:`build order`, :term:`dependency graph`,
-      constraints, logs, and per-package build artifacts. See :doc:`/files`.
+      constraints, logs, and per-package build artifacts. See :doc:`/reference/files`.

docs/config-reference.rst docs/reference/config-reference.rstdocs/config-reference.rst renamed to docs/reference/config-reference.rst

@@ -0,0 +1,47 @@
+Reference
+=========
+
+This section contains detailed technical reference documentation for Fromager.
+
+Command Line Interface
+----------------------
+
+Complete documentation of all fromager CLI commands and options.
+
+.. toctree::
+   :maxdepth: 2
+
+   cli.rst
+
+Configuration
+-------------
+
+Comprehensive configuration reference for customizing package builds.
+
+.. toctree::
+   :maxdepth: 2
+
+   config-reference.rst
+   hooks.rst
+
+Files and Formats
+-----------------
+
+Documentation of input/output files and data formats used by fromager.
+
+.. toctree::
+   :maxdepth: 2
+
+   files.md
+   glossary.rst
+
+Quick Reference
+---------------
+
+Looking for something specific?
+
+* **CLI Commands**: See :doc:`cli` for the complete command reference
+* **Package Settings**: See :doc:`config-reference` for per-package and global settings
+* **Override Plugins**: See :doc:`hooks` for customization hooks and extension points
+* **File Formats**: See :doc:`files` for details on ``build-order.json``, ``graph.json``, and output directories
+* **Terminology**: See :doc:`glossary` for definitions of key terms