docs: improved documentation structure and rendering

- Fixed literalinclude rendering in customization.md with MyST colon_fence
- Moved skip-constraints example to multiple-versions how-to guide
- Updated conf.py: fixed typos, use dynamic copyright year, added MyST extension

Signed-off-by: Martin Prpič <[email protected]>

Author: mprpic

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/[email protected]
 ```
 
-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

@@ -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