overhaul elements of index.rst and inst.rst #497

bconsolvo · 2025-10-10T14:19:56Z

Overhaul of index.rst and inst.rst for ease of use for developers

Keeping release notes with only actual release notes, not hardware configurations. Moved hardware configuration and model support to index (starting page), and adjusted other links elsewhere to point to this place.
Added HW support table to provide much more clarity on codenames and supported OS for 1.6.0 release
Added links for installation into table of prerequisites
Added code for setting environment variables in PowerShell (not obvious from documentation)
Added 5-step development workflow overview cycle to clarify a typical development cycle
Other small syntactical and structural changes

merging changes to highlight automatic BF16 conversion

Copilot

Pull Request Overview

This PR overhauls the documentation structure for index.rst and inst.rst to improve ease of use for developers. Key changes include reorganizing hardware configuration information, adding clearer installation instructions, and providing a structured development workflow overview.

Moved hardware configuration and model support information from release notes to the main index page
Enhanced installation instructions with specific links and PowerShell environment variable setup
Added a 5-step development workflow overview for typical Ryzen AI usage
Updated example titles and restructured documentation organization

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/relnotes_backup.rst	Created as backup containing original release notes content with hardware configurations
docs/relnotes.rst	Removed hardware configuration sections to focus on actual release notes
docs/inst.rst	Enhanced with detailed prerequisites table, PowerShell setup code, and clearer installation steps
docs/index.rst	Added comprehensive hardware support tables and development workflow overview
docs/getstartex.rst	Updated tutorial title and added more detailed explanations
docs/examples.rst	Simplified structure and updated example titles
docs/conf.py	Added sphinx_copybutton extension for code block copying

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

docs/inst.rst

docs/getstartex.rst

ThomasXilinx · 2025-10-15T16:42:47Z

docs/examples.rst

 NPU
 ~~~

- :doc:`Getting Started Tutorial for INT8 models <getstartex>` - Uses a custom ResNet model to demonstrate: 


Why remove "Getting Started" from the description?

Can leave it in if you want. It is self-explanatory that it is for "getting started"

ThomasXilinx · 2025-10-15T16:49:57Z

docs/index.rst

+     - 2025
+     - ☑️
+     - 
+   * - Ryzen Z2


I don't believe this device is supported.

Okay, can be removed then.

ThomasXilinx · 2025-10-15T16:52:13Z

docs/index.rst

+****************
+Ryzen AI 1.6 Software runs on AMD processors outlined below. For a more detailed list of supported devices, refer to the `processor specifications <https://www.amd.com/en/products/specifications/processors.html>`_ page (scroll to the "AMD Ryzen™ AI" column toward the right side of the table, and select "Available" from the pull-down menu). Support for Linux is coming soon in Ryzen AI 1.6.1.
+
+.. list-table:: Supported Ryzen AI Processor Configurations


This table will only grow and will be hard to maintain as we add support for more platforms. It's redundant with the https://www.amd.com/en/products/specifications/processors.html page. And we risk creating inconsistencies. Case in point, see the comment about Z2 below.

I recommend we simply link to the official processor specification page.

That processors page you linked is very hard to navigate. You have to scroll across multiple screens just to find the info you need. It would be nice to have some kind of compatibility table right on the docs site. It doesn't have to be as broad as what I've described. But I am confused when there is no table to summarize what processor goes with what abbreviation throughout the docs. People only know the "STX", "KRK" and other abbreviations internal to AMD.

ThomasXilinx · 2025-10-15T16:54:28Z

docs/index.rst

+     - GPU
+     - NPU
+     - Hybrid (NPU + iGPU)
+   * - Ryzen AI 300


We support LLMs on all STX and KRK platforms, not all Ryzen AI 300. The first column in this table is not needed and should be removed.

The whole point is to relate the processor series name to the codename here. It is confusing as to what the common name people refer to it as, versus the codename.

ThomasXilinx · 2025-10-15T16:56:31Z

docs/index.rst

+.. list-table::
+   :header-rows: 1
+
+   * - Model Type


Why mention CPU and GPU for LLMs and not for other models? BF16 models can run on CPU and GPU on PHX/HPT.
The way LLMs and CNN/NLPs are presented in inconsistent. It would be preferable to find a common way to presenting the information.

Okay, open to your suggestions as to a better way to present it; but I think a table does a good job of communicating the information.

ThomasXilinx · 2025-10-15T16:59:24Z

docs/index.rst

 *************************

-The Ryzen AI development flow does not require any modifications to the existing model training processes and methods. The pre-trained model can be used as the starting point of the Ryzen AI flow.
+A typical Ryzen AI flow might look like the following:


This is accurate for CNNs, but not for BF16 NLPs (no quantization step) or LLMs (OGA flow).

Then adding "for CNNs" is fine.

ThomasXilinx · 2025-10-15T17:04:15Z

docs/inst.rst

+     - 2022 with `Desktop Development with C++` checked
+   * - `cmake <https://cmake.org/download/>`_
+     - >= 3.26
+   * - `Python (Miniforge preferred) <https://conda-forge.org/download/>`_


Should we really say "Miniforge preferred"?
Internally to AMD, we need to use Miniforge. But other companies may have different requirements.

Can remove that statement. The point here was to add links for suggestions of where to get the packages they need. It's fine to link Conda / Anaconda as well, but I thought it was better to have links for developers to get what they need, rather than having no links and just having people to go off and find what they need.

ThomasXilinx · 2025-10-15T17:04:38Z

docs/inst.rst

- Miniforge: ensure that the following path is set in the System PATH variable: ``path\to\miniforge3\condabin`` or ``path\to\miniforge3\Scripts\`` or ``path\to\miniforge3\`` (The System PATH variable should be set in the *System Variables* section of the *Environment Variables* window).
+  $existingPath = [System.Environment]::GetEnvironmentVariable('Path', 'Machine')
+
+.. code-block:: powershell


Why not put all 3 lines in the same code block?

Sure. The point here was to add actual Powershell code, rather than bash code when people are working on Windows.

ThomasXilinx · 2025-10-15T17:05:11Z

docs/inst.rst

+
+.. code-block:: powershell
+
+  $newPaths = "C:\Users\<user>\miniforge3\Scripts;C:\Users\<user>\miniforge3\condabin"


This will only work for miniforge. If people have Anaconda or Miniconda, this will not work.

Can just be resolved by saying "May need to adjust paths according to your conda installation."

ThomasXilinx

Some of the proposed changes need more discussion

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

bconsolvo · 2025-12-05T15:33:17Z

Added comments to the changes. Thanks for the feedback.

dwithchenna and others added 8 commits October 8, 2025 16:00

Merge pull request amd#495 from amd/develop

b08189d

merging changes to highlight automatic BF16 conversion

HW support table and LLM Support table

34fa6ef

index and installation updates

8f5bb95

installation readme updates

7c7344a

syntax of bullets

6e34db3

windows install wording

4f8f6d4

added back cmake in table

ddd814c

syntax for title Windows Installation Instructions

26e743d

dwithchenna requested review from ThomasXilinx, Copilot, dwithchenna and uday610 October 15, 2025 03:56

dwithchenna assigned bconsolvo Oct 15, 2025

dwithchenna added the documentation Improvements or additions to documentation label Oct 15, 2025

Copilot AI reviewed Oct 15, 2025

View reviewed changes

docs/inst.rst Outdated Show resolved Hide resolved

docs/inst.rst Outdated Show resolved Hide resolved

docs/getstartex.rst Outdated Show resolved Hide resolved

docs/getstartex.rst Show resolved Hide resolved

ThomasXilinx reviewed Oct 15, 2025

View reviewed changes

ThomasXilinx requested changes Oct 15, 2025

View reviewed changes

bconsolvo and others added 4 commits December 5, 2025 08:15

Update docs/inst.rst

0c541fd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/inst.rst

5f351c0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/getstartex.rst

7aade12

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/getstartex.rst

d994026

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

dwithchenna deleted the branch amd:develop January 6, 2026 20:15

dwithchenna closed this Jan 6, 2026


		.. code-block:: powershell

		$newPaths = "C:\Users\<user>\miniforge3\Scripts;C:\Users\<user>\miniforge3\condabin"

overhaul elements of index.rst and inst.rst #497

overhaul elements of index.rst and inst.rst #497

Uh oh!

Conversation

bconsolvo commented Oct 10, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bconsolvo Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ThomasXilinx left a comment

Choose a reason for hiding this comment

Uh oh!

bconsolvo commented Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bconsolvo Dec 5, 2025 •

edited

Loading