docs: add quick start guide and glossary from learning-fromager repo

Add quickstart.rst with installation instructions and a simple stevedore exampl for new users. Add glossary.md with terminology definitions. Update getting-started.rst to point new users to the quick start guide.

Content adapted from the learning-fromager repository.

Signed-off-by: shifa-khan shikhan@redhat.com
Closes: #799

Author: shifa-khan

docs/getting-started.rst

@@ -1,6 +1,10 @@
 Getting Started
 ===============
 
+.. note::
+
+   New to fromager? Start with :doc:`quickstart` for a simple first build.
+
 The basic process for using fromager to build a collection of wheels is
 
 1. Make a list of the top-level dependencies (applications, extension libraries,

docs/glossary.md

@@ -0,0 +1,117 @@
+# Glossary
+
+Reference for terminology used throughout fromager documentation.
+
+## Package Formats
+
+**sdist (Source Distribution)** is an archive containing Python source code,
+typically a `.tar.gz` file. It must be compiled to be installed.
+
+**wheel** is a pre-built binary distribution (`.whl` file) that can be
+installed directly without compilation.
+
+## Package Naming
+
+**canonical name** is the normalized form of a package name following Python
+packaging standards. It's lowercase with hyphens, so `My-Package` becomes
+`my-package`.
+
+**override name** is the module-safe version used for settings files and
+plugins. Hyphens become underscores, so `my-package` becomes `my_package`.
+
+## Dependency Types
+
+**build-system dependencies** are the minimal tools needed to understand how
+to build a package. These are specified in `[build-system] requires` in
+`pyproject.toml`. Examples include `setuptools`, `hatchling`, and `flit-core`.
+
+**build-backend dependencies** are additional dependencies discovered by
+calling the build backend's `get_requires_for_build_wheel()` hook. For example,
+a package with Cython extensions might need `cython`.
+
+**build-sdist dependencies** are dependencies specifically needed for creating
+source distributions, returned by `get_requires_for_build_sdist()`.
+
+**install dependencies** are packages needed when using the built package.
+They come from `Requires-Dist` in the wheel metadata.
+
+**top-level dependencies** are the requirements you specify directly in your
+`requirements.txt`, as opposed to dependencies discovered through resolution.
+
+## Requirements vs Constraints
+
+**requirement** specifies a package you want to build. It can include version
+constraints like `requests>=2.25.0`.
+
+**constraint** limits which version is selected during resolution without
+requesting the package directly. Constraints are useful for resolving conflicts
+or pinning transitive dependencies.
+
+A common pattern is to separate them:
+
+```text
+# requirements.txt - what you want to build
+requests
+flask
+
+# constraints.txt - version limits for everything
+requests>=2.25.0
+urllib3==2.2.3
+```
+
+## Build Concepts
+
+**bootstrap** is the recursive process of building a package and all its
+dependencies from source. Fromager figures out the correct build order
+automatically.
+
+**build order** is the sequence in which packages must be built. It's a
+topological sort of the dependency graph, so each package's dependencies
+are built before the package itself.
+
+**variant** is a named build configuration for different scenarios like
+`cpu`, `gpu`, or `cuda`. Variants control environment variables and settings
+on a per-package basis.
+
+**resolver** is the component that determines which version of a package
+to use based on requirements and constraints.
+
+## Customization
+
+**override** provides package-specific custom behavior, such as a custom
+source URL or build commands.
+
+**hook** is an extension point for cross-cutting concerns like post-build
+actions. Multiple plugins can handle the same hook.
+
+**patch** is a file containing source code modifications applied before
+building. Patches are placed in `overrides/patches/<package_name>/`.
+
+**settings file** is a YAML configuration for package-specific build behavior,
+located in `overrides/settings/<package_name>.yaml`.
+
+## Build Isolation
+
+**network isolation** means running builds without network access, using Linux
+namespaces. This ensures builds use only local or vendored dependencies.
+
+**build isolation** means each package builds in its own virtual environment
+to prevent interference between packages.
+
+**vendoring** means including dependencies within a package's source for
+offline builds. This is common for Rust dependencies in Python packages.
+
+## Version Terms
+
+**pre-release** refers to development versions like `1.0.0a1` or `1.0.0rc1`.
+These are not selected by default unless explicitly requested.
+
+**specifier** is the version range part of a requirement, like `>=1.0,<2.0`.
+
+## See Also
+
+For detailed explanation of output directories and files, see [files](files.md).
+
+For how to use settings, patches, and variants, see [customization](customization.md).
+
+For technical details of the bootstrap process, see [using](using.md).

docs/index.rst

@@ -27,6 +27,7 @@ those special cases directly into fromager.
    :maxdepth: 2
 
    using.md
+   quickstart.rst
    getting-started.rst
    customization.md
    concepts/index.rst

docs/quickstart.rst

@@ -0,0 +1,83 @@
+Quick Start
+===========
+
+This guide gets you from zero to your first wheel build in under 5 minutes.
+
+Prerequisites
+-------------
+
+You'll need Python 3.11 or later and network access to download packages from PyPI.
+
+Installation
+------------
+
+Install fromager using pip:
+
+.. code-block:: console
+
+   $ pip install fromager
+   $ fromager --version
+   fromager, version X.Y.Z
+
+Your First Build
+----------------
+
+Let's build a simple package and its dependencies from source. We'll use
+``stevedore``, a lightweight package with minimal dependencies.
+
+Create a ``requirements.txt`` file with the package name:
+
+.. code-block:: console
+
+   $ echo "stevedore" > requirements.txt
+
+Run the bootstrap command:
+
+.. code-block:: console
+
+   $ fromager bootstrap -r requirements.txt
+
+   primary settings file: overrides/settings.yaml
+   per-package settings dir: overrides/settings
+   variant: cpu
+   ...
+   100%|████████████████████████████████████████| 3/3 [00:08<00:00,  2.67s/pkg]
+   writing installation dependencies to ./work-dir/constraints.txt
+
+Check your results:
+
+.. code-block:: console
+
+   $ ls wheels-repo/downloads/
+   pbr-6.1.0-0-py2.py3-none-any.whl
+   setuptools-75.1.0-0-py3-none-any.whl
+   stevedore-5.3.0-0-py3-none-any.whl
+
+You've built ``stevedore`` and its dependencies (``pbr``, ``setuptools``)
+entirely from source. Fromager downloaded the source distributions from PyPI,
+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`.
+
+Pinning Versions with Constraints
+---------------------------------
+
+For reproducible builds, use a constraints file to pin specific versions:
+
+.. code-block:: console
+
+   $ echo "stevedore==5.3.0" > constraints.txt
+   $ fromager -c constraints.txt bootstrap -r requirements.txt
+
+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:
+
+* 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`