Content Development Guide

August 5, 2026 · View on GitHub

Guide for adding and modifying generated content in AWS Deep Learning Containers documentation. For site setup and local development, see README.md.

Directory Structure

docs/
├── src/
│   ├── data/                                           # Per-image configuration files
│   │   ├── template/
│   │   │   └── image-template.yml                      # Template with all fields documented
│   │   ├── pytorch-training/
│   │   │   └── <version>-<accelerator>-<platform>.yml  # Naming is for organization only
│   │   └── ...
│   ├── legacy/                                         # Historical support data
│   │   └── legacy_support.yml
│   ├── tables/                                         # Table column configurations
│   │   └── <repository>.yml
│   ├── templates/
│   │   ├── reference/                                  # Reference page templates
│   │   └── releasenotes/                               # Release notes templates
│   ├── constants.py                                    # Path constants and GLOBAL_CONFIG
│   ├── generate.py                                     # Generation logic
│   ├── global.yml                                      # Shared terminology and configuration
│   ├── hooks.py                                        # MkDocs hooks
│   ├── image_config.py                                 # ImageConfig class
│   ├── macros.py                                       # MkDocs macros plugin
│   ├── main.py                                         # CLI entry point
│   ├── sorter.py                                       # Sorting tiebreaker functions
│   └── utils.py                                        # Utility functions
├── reference/                                          # Generated reference pages
├── releasenotes/                                       # Generated release notes
└── mkdocs.yml

Adding a New Image

Step 1: Create Image Config

Create docs/src/data/<repository>/<version>-<accelerator>-<platform>.yml:

# Required fields
framework: PyTorch
version: "2.9"
accelerator: gpu              # gpu, cpu, or neuronx
platform: ec2                 # ec2 or sagemaker
tags:
  - "2.9.0-gpu-py312-cu130-ubuntu22.04-ec2"

# Optional metadata
python: py312
cuda: cu130
os: ubuntu22.04
public_registry: true

The YAML file name is for organizational purposes only. However, make sure that the image configuration file lives in the correct repository directory.

See docs/src/data/template/image-template.yml for all available fields.

Step 2: Regenerate

python docs/src/main.py --verbose

Adding Support Policy Dates

Add ga and eop fields to image configs for repositories that appear in support policy:

ga: "2025-10-15"    # General Availability date
eop: "2035-10-15"   # End of Patch date

Version Consolidation:

Images with the same major.minor version and identical GA/EOP dates are consolidated into a single row displayed as 2.6 with the framework group name (e.g., "PyTorch")
If the same version has different GA/EOP dates across repository types (e.g., training vs inference), separate rows are created showing the specific repository type: "PyTorch Training" and "PyTorch Inference"
ARM64 variants are automatically consolidated with their base repository
If patch versions within the same repository have different GA/EOP dates, each is displayed separately with full version (e.g., 2.6.0, 2.6.1) and a warning is logged

Flexibility: Repositories in the same framework group (e.g., pytorch-training and pytorch-inference) can have different GA/EOP dates for the same version. The system will automatically create separate rows showing the specific repository type when dates differ.

Example: If PyTorch 2.6 Training has EOP 2025-10-15 but PyTorch 2.6 Inference has EOP 2026-10-15, the support policy table will show two separate rows with "PyTorch Training" and "PyTorch Inference" in the Framework column.

Adding Release Notes

Add these fields to an image config:

announcements:
  - "Introduced containers for PyTorch 2.9"
  - "Added Python 3.12 support"

packages:
  python: "3.12"
  pytorch: "2.9.0"
  cuda: "13.0"

# Optional sections (rendered dynamically)
optional:
  known_issues:
    - "Description of known issue"

Release notes are generated automatically for images with announcements and packages fields.

Adding New Optional Sections

Add section to image config under optional:

optional:
  known_issues:
    - "Issue 1"
  deprecation_notice:
    - "This image will be deprecated..."

Add display name to global.yml:

display_names:
  repositories:
    deprecation_notice: "Deprecation Notice"

Sections render in YAML order as bullet lists.

Section headers in optional sections are rendered via the section key. To format your optional section headers, add a new field in docs/src/global.yml under display_names.repositories. Eg: deprecation_notice section will render its header as ## deprecation_notice unless a formatted string is provided in docs/src/global.yml.

Adding a New Repository

Create directory: docs/src/data/<repository>/

Create table config docs/src/tables/<repository>.yml:

columns:
  - field: framework_version
    header: "Framework"
  - field: python
    header: "Python"
  - field: example_uri
    header: "Example URI"

Add to docs/src/global.yml:

display_names:
  repositories:
    my-repo: "My Repository"

table_order:
  - my-repo

Editing Table Columns

Edit docs/src/tables/<repository>.yml:

columns:
  - field: framework_version
    header: "Framework"
  - field: python
    header: "Python"
  # Add/remove/reorder columns here

Available fields: framework_version, python, cuda, sdk, accelerator, platform, os, example_uri, version, ga, eop, framework_group, repository, release_note_link To add additional fields, ensure that the image configuration YAML file contains said field of the same name. Additionally, if you require the field to be formatted, add an additional attribute in ImageConfig class of display_<field_name> to grab the formatted field.

Legacy Support Data

Historical data for unsupported images in docs/src/legacy/legacy_support.yml:

pytorch:
  - version: "2.5"
    ga: "2024-10-29"
    eop: "2025-10-29"

Generally, this is only required if an image configuration file does not already exist and the image is already past its support.

Global Configuration

docs/src/global.yml contains:

Terminology: aws, dlc_long, sagemaker, etc.
display_names.repositories: Repository and section-header display names (used in available_images.md, support_policy.md, and release-note titles)
display_names.packages: Package display labels rendered in the Core Packages table of release notes
framework_groups: Support policy consolidation groups
table_order: Order of tables displayed within the documentations website (eg: available_images.md and support_policy.md)
platforms/accelerators: Display mappings

Tutorials Changes

For any changes required to the tutorial pages, create a new PR in aws-samples/sample-aws-deep-learning-containers.

Important: When making changes to the tutorials page, make sure that you update the tutorials index.md and .nav.yaml accordingly.

Troubleshooting

Error	Solution
"Display name not found"	Add repository to `display_names.repositories` in `global.yml`
"Inconsistent dates"	Ensure all images in same framework group/version have identical GA/EOP
Images not appearing	Check repository is in `table_order`
Release notes not generating	Ensure `announcements` and `packages` fields are present