project-setup-python

name	project-setup-python
version	1.15.0
license	Apache-2.0
description	Author usd-profiles-nvidia specs and generate Python enums from Markdown/TOML. Do NOT use for USD asset validation.
metadata	{"author":"NVIDIA","tags":["usd-profiles-nvidia","codegen","profile-specs"]}
compatibility	Requires Python 3.10-3.12, uv or pip, network access to Python package indexes, and Linux/macOS shell or Windows PowerShell command syntax.

Python Project Setup

Purpose

usd-profiles-nvidia reads structured Markdown and TOML profile specs and generates a Python package with requirement, capability, feature, and profile enums. Use this skill for usd-profiles-nvidia code generation only; downstream integration belongs in a separate project.

Prerequisites

• Python 3.10-3.12.
• uv or pip with package-index access.

Project Structure

examples/python/minimal/
  pyproject.toml
  specs/
    capabilities/
      capability-example.md
      requirements/
        single-root.md
    features/
      feature-example.md
    profiles/
      profile-example.md
      profiles.toml.example

Setup with uv (Recommended)

Use uv to run codegen without creating a local virtual environment:

uv run \
  --no-project \
  --with . \
  python -m usd_profiles_nvidia.codegen --help

Note: replace --with . with --with usd-profiles-nvidia to use the public build.

The example project file lists the package dependency:

Source: examples/python/minimal/pyproject.toml

Setup with pip

Install the codegen package into an environment you control:

python -m pip install usd-profiles-nvidia

Then run python -m usd_profiles_nvidia.codegen with the same arguments shown below.

Minimal specs / Minimal example

The example contains one requirement, one capability, one feature, and one profile.

Source: examples/python/minimal/specs/capabilities/requirements/single-root.md

Source: examples/python/minimal/specs/capabilities/capability-example.md

Source: examples/python/minimal/specs/features/feature-example.md

Source: examples/python/minimal/specs/profiles/profile-example.md

Optional TOML profile format: examples/python/minimal/specs/profiles/profiles.toml.example

Run

From the repository root:

uv run \
  --no-project \
  --with . \
  python -m usd_profiles_nvidia.codegen \
    --docs-root examples/python/minimal/specs \
    --destination-dir _build/minimal \
    --package-name example_profiles

Note: replace --with . with --with usd-profiles-nvidia to use the public build.

Generated files appear under _build/minimal/example_profiles.

Key Dependencies

Package	Purpose
usd-profiles-nvidia	Parses specs and generates Python enums
uv	Runs the package without a checked-in virtual environment
usd-profiles-nvidia[sphinx]	Optional Sphinx documentation integration; not required for codegen

Limitations

• Covers profile spec authoring and enum code generation only; downstream USD asset validation belongs elsewhere.
• Does not configure Sphinx documentation builds beyond noting optional dependencies.

Common Pitfalls

• Use --package-name; the older namespace option is deprecated.
• Keep capabilities/, features/, and profiles/ under the docs root passed to codegen.
• Leave profiles.toml.example with the .example suffix unless you want TOML profiles to replace profile-*.md parsing.
• Match features-table entries to requirement codes and versions, such as EX.001@1.0.0.
• Keep this workflow focused on profile code generation.

Troubleshooting

• If codegen cannot find capabilities, features, or profiles, confirm their folders are under the --docs-root path.
• If generated imports use the wrong package path, rerun codegen with the intended --package-name value.