cleanup structure

docs/conf.py

@@ -10,7 +10,7 @@
 from rocm_docs import ROCmDocs
 
 # ROCm version numbers
-rocm_version = '6.0.0' 
+rocm_version = '6.0.0'
 amdgpu_version = '6.0.0' # directory in # directory in https://repo.radeon.com/rocm/apt/https://repo.radeon.com/amdgpu-install/
 amdgpu_install_version = '6.0.60000-1' # version in https://repo.radeon.com/amdgpu-install/5.7.1/ubuntu/focal/
 
@@ -46,7 +46,7 @@
 
 external_toc_path = "./sphinx/_toc.yml"
 
-docs_core = ROCmDocs("Linux Installation")
+docs_core = ROCmDocs("ROCm installation (Linux)")
 docs_core.setup()
 
 external_projects_current_project = "rocm"

docs/how-to/3rd-party/pytorch-install.rst

@@ -16,8 +16,8 @@ To install `PyTorch for ROCm <https://pytorch.org/blog/pytorch-for-amd-rocm-plat
 
 For hardware, software, and third-party framework compatibility between ROCm and PyTorch, refer to:
 
-* :doc:`/reference/system-requirements`
-* :doc:`/reference/3rd-party-support-matrix`
+* :ref:`system-requirements`
+* :doc:`3rd-party-support-matrix`
 
 .. _using-docker-with-pytorch-pre-installed:
 
@@ -88,7 +88,7 @@ wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matr
 
    **Option 2:**
 
-   Select a base OS Docker image (Check :doc:`/reference/system-requirements`)
+   Select a base OS Docker image (Check :ref:`system-requirements`)
 
    Pull selected base OS image (Ubuntu 20.04 for example)
 
@@ -102,12 +102,12 @@ wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matr
 
        docker run -it --device=/dev/kfd --device=/dev/dri --group-add video ubuntu:20.04
 
-   Install ROCm using the directions in the :doc:`Installation section </how-to/index>`.
+   Install ROCm using the directions in the :ref:`rocm-install-overview` section.
 
    **Option 3:**
 
-   Install on bare metal. Check :doc:`/reference/system-requirements` and install ROCm using the
-   directions in the :doc:`Installation section </how-to/index>`.
+   Install on bare metal. Check :ref:`system-requirements` and install ROCm using the
+   directions in the  :ref:`rocm-install-overview` section.
 
 2. Install the required dependencies for the wheels package.
 

docs/index.rst

@@ -1,29 +1,60 @@
-ROCm™ Linux Installation 
-########################
+.. _rocm-install-home:
+
+****************************************************************
+ROCm™ Linux installation
+****************************************************************
+
+If you're new to ROCm, we recommend using the :ref:`rocm-install-quick` guide. If you want more
+complete instructions, refer to the following sections.
+
+Prepare to install
+========================================
 
 .. grid:: 2
     :gutter: 1
-
-    .. grid-item-card:: Reference
+
+    .. grid-item-card:: Prerequisites
+        :link: how-to/prerequisites.rst
+
+        The prerequisites page lists the required steps *before* installation.
+
+    .. grid-item-card:: Install options
+        :link: /tutorial/install-overview.rst
+
+        Package manager vs AMDGPU installer
+
+        Single-version vs multi-version
+
+Choose your install method
+========================================
+
+.. grid:: 2
+    :gutter: 1
+
+    .. grid-item-card:: Package manager
+        :link: how-to/native-install/index.rst
+
+        Directly use your distribution's package manager to install ROCm.
+
+    .. grid-item-card:: AMDGPU installer
+        :link: how-to/amdgpu-install.rst
+
+        Use an installer tool that orchestrates changes via the package manager.
+
+Additional resources
+========================================
+
+.. grid:: 2
+    :gutter: 1
+
+    .. grid-item-card:: Reference material
 
         - :doc:`reference/system-requirements`
         - :doc:`reference/docker-image-support-matrix`
         - :doc:`reference/3rd-party-support-matrix`
 
-    .. grid-item-card:: How to Guides
+    .. grid-item-card:: Tutorials
 
-        - :doc:`how-to/prerequisites`
-        - :doc:`how-to/native-install/index`
-            - :doc:`how-to/native-install/ubuntu`
-            - :doc:`how-to/native-install/rhel`
-            - :doc:`how-to/native-install/sle`
-        - :doc:`how-to/amdgpu-install`
-        - Third Party Packages
             - :doc:`how-to/3rd-party/magma-install`
             - :doc:`how-to/3rd-party/pytorch-install`
-            - :doc:`how-to/3rd-party/tensorflow-install`
-
-    .. grid-item-card:: Tutorials
-
-        - :doc:`tutorial/quick-start`
-        - :doc:`tutorial/install-overview`
+            - :doc:`how-to/3rd-party/tensorflow-install`

docs/reference/3rd-party-support-matrix.rst

@@ -1,3 +1,5 @@
+.. _3rd-party-support-matrix:
+
 Third Party Support Matrix
 ##########################
 

docs/reference/docker-image-support-matrix.rst

@@ -1,3 +1,5 @@
+.. _docker-support-matrix:
+
 ******************************************************************
 Docker image support matrix
 ******************************************************************

docs/reference/system-requirements.rst

@@ -1,3 +1,5 @@
+.. _system-requirements:
+
 System Requirements
 ###################
 

docs/sphinx/_toc.yml.in

@@ -3,18 +3,15 @@ defaults:
   maxdepth: 6
 root: index
 subtrees:
-- caption: Tutorials
-  entries:
+- entries:
     - file: tutorial/quick-start
-    - file: tutorial/install-overview
-
-- caption: How to Guides
-  entries:
-    - file: how-to/index
+      title: Quick-start install guide
+    - file: how-to/prerequisites
+      title: Prerequisites
     - file: how-to/amdgpu-install
       title: Installation via AMDGPU Installer
     - file: how-to/native-install/index
-      title: Installation via Package Manager
+      title: Installation via package manager
       subtrees:
       - entries:
         - file: how-to/native-install/ubuntu
@@ -26,20 +23,31 @@ subtrees:
         - file: how-to/native-install/post-install
           title: Post-Install Instructions
         - file: how-to/native-install/package-manager-integration
-          title: Package Manager Integration
-    - file: how-to/prerequisites
-    - file: how-to/docker
-    - file: how-to/spack
-    - file: how-to/3rd-party/index
-      subtrees:
-        - entries:
-          - file: how-to/3rd-party/magma-install
-          - file: how-to/3rd-party/pytorch-install
-          - file: how-to/3rd-party/tensorflow-install
+          title: Package manager integration
+
+- caption: Tutorials
+  entries:
+  - file: how-to/3rd-party/magma-install
+    title: Install Magma
+  - file: how-to/3rd-party/pytorch-install
+    title: Install PyTorch
+  - file: how-to/3rd-party/tensorflow-install
+    title: Install TensorFlow
+
+- caption: How-to
+  entries:
+  - file: how-to/docker
+    title: Install Docker containers
+  - file: how-to/spack
+    title: Introduction to Spack
 
 - caption: Reference
   entries:
     - file: reference/system-requirements
+      title: System requirements
     - file: reference/3rd-party-support-matrix
+      title: Third-party support
     - file: reference/docker-image-support-matrix
+      title: Docker image support
     - file: reference/user-kernel-space-compat-matrix
+      title: Kernel-space support

docs/tutorial/install-overview.rst

@@ -1,23 +1,28 @@
-ROCm Installation Options
-#########################
+.. _rocm-install-overview:
 
-Users installing ROCm must choose between various installation options. A new
-user should follow the :doc:`quick-start` guide.
+*************************************************************
+ROCm installation options
+*************************************************************
+
+To install ROCm, you can use the AMDGPU installer or the package manager. You can also opt for
+single-version or multi-version installation. These topics are described in detail in the following
+sections.
+
+If you're new to ROCm, we recommend using the :ref:`rocm-install-quick` guide.
 
 .. note::
-    See :doc:`Radeon Installation instructions <radeon:install/install-radeon>`
-    for those using the Radeon GPU with graphical applications.
+    If you're using the Radeon GPU with graphical applications, see
+    :doc:`Radeon Installation instructions <radeon:install/install-radeon>`.
 
-Package Manager and AMDGPU Installer differences
-************************************************
+Package manager versus AMDGPU installer
+===========================================================
 
 ROCm supports two methods for installation:
 
-- Directly using the Linux distribution's package manager
-- The ``amdgpu-install`` script
+- Using the Linux distribution package manager
+- Running the ``amdgpu-install`` script
 
-There is no difference in the final installation state when choosing either
-option.
+There is no difference in the final installation between these two methods.
 
 Using the distribution's package manager lets the user install,
 upgrade and uninstall using familiar commands and workflows. Third party
@@ -35,21 +40,22 @@ installation.
 
 .. _installation-types:
 
-Single Version ROCm install versus Multi-Version
-************************************************
+Single-version versus multi-version installation
+===========================================================
 
 ROCm packages are versioned with both semantic versioning that is package
 specific and a ROCm release version.
 
-### Single-version Installation
+Single-version installation
+---------------------------------------------------------------------------------
 
 The single-version ROCm installation refers to the following:
 
 - Installation of a single instance of the ROCm release on a system
 - Use of non-versioned ROCm meta-packages
 
-Multi-version Installation
-==========================
+Multi-version installation
+---------------------------------------------------------------------------------
 
 The multi-version installation refers to the following:
 
@@ -64,7 +70,7 @@ The multi-version installation refers to the following:
     conflicts.
 
 .. note::
-    Multiversion install is not available for the kernel driver module, also referred to as AMDGPU.
+    Multi-version install is not available for the kernel driver module, also referred to as AMDGPU.
 
 The following image demonstrates the difference between single-version and
 multi-version ROCm installation types: