Merge pull request #835 from mprpic/add-source-hook-helper-docs

Add source hook helper docs and other docs fixes

Author: mergify[bot]

docs/conf.py

@@ -15,7 +15,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Fromager"
-copyright = "2024, Fromager Authors"
+copyright = "%Y, Fromager Authors"
 author = "Fromager Authors"
 release = metadata.version("fromager")
 
@@ -30,14 +30,19 @@
     "sphinx.ext.intersphinx",
 ]
 
+# Enable MyST extensions to support reStructuredText directives in Markdown
+myst_enable_extensions = [
+    "colon_fence",
+]
+
 # Recognized suffixes
 source_suffix = {
     ".rst": "restructuredtext",
     ".md": "markdown",
 }
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "example"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 language = "English"
 
@@ -67,7 +72,7 @@
 
 
 class FromagerHookDocumenter(FunctionDocumenter):
-    """Documenter for 'autofromagehook' directive"""
+    """Documenter for 'autofromagerhook' directive"""
 
     objtype = "fromagerhook"
 
@@ -79,7 +84,7 @@ def format_name(self):
 
 
 class PyFromagerHook(PyFunction):
-    """:py:fromagehook"""
+    """:py:fromagerhook"""
 
     def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
         # hack to remove module prefix from output

docs/customization.md

@@ -154,15 +154,17 @@ bootstrap requirements, such as:
 my-package @ git+https://github.com/example/repo.git@v1.2.3
 ```
 
-For example requirements with git URLs, see:
+Example requirements file with Git URLs:
 
-.. literalinclude:: example/requirements-git-example.txt
-   :caption: requirements-git-example.txt
+```{literalinclude} example/requirements-git-example.txt
+:caption: requirements-git-example.txt
+```
 
-For a complete package configuration example, see:
+A complete package configuration example:
 
-.. literalinclude:: example/git-submodules-example.yaml
-   :caption: git-submodules-example.yaml
+```{literalinclude} example/git-submodules-example.yaml
+:caption: git-submodules-example.yaml
+```
 
 ### Build directory
 

docs/example/skip-constraints-example.md

@@ -240,6 +240,17 @@ Source hooks
 
     The return value is the ``Path`` to the newly created source distribution.
 
+Source helper functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following helper functions are available in the ``fromager.sources`` module
+for use in custom source hooks:
+
+.. autofunction:: fromager.sources.ensure_pkg_info
+
+.. autofunction:: fromager.sources.pep517_build_sdist
+
+.. autofunction:: fromager.sources.unpack_source
 
 Wheel hooks
 -----------

docs/hooks.rst

@@ -57,3 +57,74 @@ Important Considerations
 The graph and build-sequence files can already handle multiple conflicting
 versions, so this change simply allows bypassing the final constraints
 validation step that ensures pip-compatibility.
+
+Complete Example
+----------------
+
+This example demonstrates a complete walkthrough of using the ``--skip-constraints``
+option to build wheel collections containing conflicting package versions.
+
+Use Case
+~~~~~~~~
+
+Suppose you need to build a package index that contains multiple versions of the
+same package for different downstream consumers. For example, you might want to
+include both Django 3.2 and Django 4.0 in your collection.
+
+Requirements Files
+~~~~~~~~~~~~~~~~~~
+
+Create a requirements file with conflicting versions:
+
+**requirements-conflicting.txt**
+
+.. code-block:: text
+
+   django==3.2.0
+   django==4.0.0
+   requests==2.28.0
+
+Normally, this would fail with a conflict error because both Django versions
+cannot be installed together.
+
+Running with --skip-constraints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   fromager bootstrap --skip-constraints \
+     --sdists-repo ./sdists-repo \
+     --wheels-repo ./wheels-repo \
+     --work-dir ./work-dir \
+     -r requirements-conflicting.txt
+
+Expected Behavior
+~~~~~~~~~~~~~~~~~
+
+1. **Success**: Both Django versions will be built successfully
+2. **Output Files**:
+
+   - ``build-order.json`` - Contains build order for all packages
+   - ``graph.json`` - Contains dependency resolution graph
+   - No ``constraints.txt`` file is generated
+
+3. **Wheel Repository**: Contains wheels for both Django versions and their respective dependencies
+
+Verification
+~~~~~~~~~~~~
+
+Check that both versions were built:
+
+.. code-block:: bash
+
+   find wheels-repo/downloads/ -name "Django-*.whl"
+   # Expected output:
+   # wheels-repo/downloads/Django-3.2.0-py3-none-any.whl
+   # wheels-repo/downloads/Django-4.0.0-py3-none-any.whl
+
+Verify no constraints file was created:
+
+.. code-block:: bash
+
+   ls work-dir/constraints.txt
+   # Expected: file does not exist

docs/how-tos/multiple-versions.rst

@@ -354,6 +354,7 @@ def unpack_source(
     version: Version,
     source_filename: pathlib.Path,
 ) -> tuple[pathlib.Path, bool]:
+    """Extracts a downloaded source archive (.tar.gz or .zip file) into a standardized directory."""
     # sdist names are less standardized and the names of the directories they
     # contain are also not very standard. Force the names into a predictable
     # form based on the override module name for the requirement.
@@ -704,13 +705,13 @@ def ensure_pkg_info(
     sdist_root_dir: pathlib.Path,
     build_dir: pathlib.Path | None = None,
 ) -> bool:
-    """Ensure that sdist has a PKG-INFO file
+    """Ensure that sdist has a PKG-INFO file.
 
-    Returns True if PKG-INFO was presence, False if file was missing. The
+    Returns True if PKG-INFO is present, False if file is missing. The
     function also updates build_dir if package has a non-standard build
     directory. Every sdist must have a PKG-INFO file in the first directory.
     The additional PKG-INFO file in build_dir is required for projects
-    with non-standard layout and setuptools-scm.
+    with a non-standard layout and projects using setuptools-scm.
     """
     had_pkg_info = True
     directories = [sdist_root_dir]