Merge pull request #970 from dhellmann/docs/reorganize-documentation

docs: reorganize documentation following Diátaxis framework

Author: mergify[bot]

.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