docs: reorganize documentation following Diátaxis framework

.pre-commit-config.yaml

@@ -9,6 +9,12 @@ repos:
       - id: check-merge-conflict     # Prevents merge conflict markers
       - id: check-toml               # Validates TOML syntax
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.39.0
+    hooks:
+      - id: markdownlint
+        args: [--config, .markdownlint-config.yaml]
+
   - repo: local
     hooks:
       - id: hatch-lint

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/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
 
@@ -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/how-tos/index.rst

@@ -1,9 +1,67 @@
 How-tos
 =======
 
+Task-oriented guides for common workflows and customization scenarios.
+
+Popular Guides
+--------------
+
+Quick links to frequently used guides:
+
+* :doc:`containers` - Running fromager in containers (recommended approach)
+* :doc:`bootstrap-constraints` - Pin versions for reproducible builds
+* :doc:`graph-commands/using-graph-why` - Debug unexpected dependencies
+* :doc:`repeatable-builds` - Ensure build reproducibility
+
+Getting Started
+---------------
+
+Essential guides for initial setup and first builds.
+
+.. toctree::
+   :maxdepth: 1
+
+   containers
+   bootstrap-constraints
+
+Building Packages
+-----------------
+
+Guides for building packages from various sources and configurations.
+
+.. toctree::
+   :maxdepth: 1
+
+   build-from-git-repo
+   repeatable-builds
+   parallel
+   build-web-server
+
+Build Configuration
+-------------------
+
+Customize builds with overrides, variants, and version handling.
+
 .. toctree::
    :maxdepth: 1
-   :glob:
 
-   *
-   */index
+   pyproject-overrides
+   multiple-versions
+   pre-release-versions
+
+Analyzing Builds
+----------------
+
+Understand and debug dependency graphs and build issues.
+
+.. toctree::
+   :maxdepth: 1
+
+   graph-commands/index
+
+See Also
+--------
+
+* :doc:`/customization` - Comprehensive guide to customization options
+* :doc:`/reference/config-reference` - Configuration reference
+* :doc:`/reference/hooks` - Override plugins and hooks

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
 ---------------------------------
@@ -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/glossary.rst → docs/reference/glossary.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`.