Merge pull request #3495 from ROCm/docsfor62

mamaydeo · web-flow · commit 5e45a731640c · 2024-10-02T14:32:37.000-04:00
Update latest documentation for new design
diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
 # AMD MIGraphX
 
 AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference.
-To use MIGraphX, you can install the binaries or build from source code. Refer to the following sections
-for Ubuntu installation instructions (we'll provide instructions for other Linux distributions in the future).
 
-> [!NOTE] 
-> You must [install ROCm](https://rocm.docs.amd.com/en/latest/deploy/linux/quick_start.html) before
+>[!NOTE]
+>The published documentation is available at [MIGraphX](https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/) in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the `docs` folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
+
+> [!NOTE]
+> You must [install ROCm](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/index.html) before
 > installing MIGraphX.
 
 ## Installing from binaries
@@ -16,7 +17,7 @@ Install binaries using:
 sudo apt update && sudo apt install -y migraphx
 ```
 
-Header files and libraries are installed under `/opt/rocm-<version>`, where `<version>` is the ROCm
+Header files and libraries are installed under ``/opt/rocm-<version>``, where ``<version>`` is the ROCm
 version.
 
 ## Building from source
diff --git a/docs/dev/contributing-to-migraphx.rst b/docs/dev/contributing-to-migraphx.rst
@@ -5,24 +5,22 @@
 .. _contributing-to-migraphx:
 
 ==========================
-Contributing to MIGraphX
+Developing for MIGraphX
 ==========================
 
-This document explains the internal implementation of some commonly used MIGraphX APIs. You can utilize the information provided in this document and other documents under "Contributing to MIGraphX" section to contribute to the MIGraphX API implementation.
-Here is how some basic operations in the MIGraphX framework are performed.
+This document is intended for anyone who wants to contribute to MIGraphX. This document covers some basic operations that can be used to develop for MIGraphX. The complete source code for the example shown here can be found at `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_ on the MIGraphX repository.
 
-Performing basic operations
+More examples can be found on `the MIGraphX GitHub repository <https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx>`_.
+
+
+Adding two literals
 ----------------------------
 
 A program is a collection of modules, which are collections of instructions to be executed when calling :cpp:any:`eval <migraphx::internal::program::eval>`.
 Each instruction has an associated :cpp:any:`operation <migraphx::internal::operation>` which represents the computation to be performed by the instruction.
 
-The following code snippets demonstrate some basic operations using MIGraphX.
-
-Adding literals
-******************
+We start with a snippet of the simple ``add_two_literals()`` function::
 
-Here is a ``add_two_literals()`` function::
 
     // create the program and get a pointer to the main module
     migraphx::program p;
@@ -55,7 +53,7 @@ To compile the program for the GPU, move the file to ``test/gpu/`` directory and
     #include <migraphx/gpu/target.hpp>
 
 Adding Parameters
-*******************
+----------------------------
 
 While the ``add_two_literals()`` function above demonstrates add operation on constant values ``1`` and ``2``,
 the following program demonstrates how to pass a parameter (``x``) to a module using ``add_parameter()`` function .
@@ -86,7 +84,7 @@ To map the parameter ``x`` to an :cpp:any:`argument <migraphx::internal::argumen
     EXPECT(result.at<int>() == 6);
 
 Handling Tensor Data
-**********************
+----------------------------
 
 The above two examples demonstrate scalar operations. To describe multi-dimensional tensors, use the :cpp:any:`shape <migraphx::internal::shape>` class to compute a simple convolution as shown below::
 
@@ -132,30 +130,24 @@ By default, the buffers are allocated on the CPU when compiling for CPU and on t
 To locate the buffers on the CPU even when compiling for GPU, set the option ``offload_copy=true``.
 
 Importing From ONNX
-**********************
+----------------------------
 
 To make it convenient to use neural networks directly from other frameworks, MIGraphX ONNX parser allows you to build a :cpp:any:`program <migraphx::internal::program>` directly from an ONNX file.
 For usage, refer to the ``parse_onnx()`` function below::
 
     program p = migraphx::parse_onnx("model.onnx");
     p.compile(migraphx::gpu::target{});
 
-Sample programs
------------------
-
-You can find all the MIGraphX examples in the `Examples <https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx>`_ directory.
 
-Build MIGraphX source code
-****************************
+Build this example
+----------------------------
 
-To build a sample program `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_, use:
+Build the `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_ example with this command:
 
     make -j$(nproc) test_ref_dev_examples
 
-This creates an executable file ``test_ref_dev_examples`` in the ``bin/`` of the build directory.
+This creates the ``test_ref_dev_examples`` under ``bin/`` in the build directory.
 
 To verify the build, use:
 
     make -j$(nproc) check
-
-For detailed instructions on building MIGraphX from source, refer to the `README <https://github.com/ROCm/AMDMIGraphX#readme>`_ file.
diff --git a/docs/dev/dev_intro.rst b/docs/dev/dev_intro.rst
@@ -2,6 +2,7 @@ Developer Introduction
 ======================
 
 MIGraphX provides an optimized execution engine for deep learning neural networks.
+
 We will cover some simple operations in the MIGraphX framework here.
 For a quick start guide to using MIGraphX, look in the examples directory: ``https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx``.
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,34 +5,41 @@
 .. _index:
 
 ===========================
-AMD MIGraphX documentation
+MIGraphX documentation
 ===========================
 
-Welcome to the MIGraphX docs home page! To learn more, see :ref:`what-is-migraphx`.
+MIGraphX is a graph inference engine and graph compiler. MIGraphX accelerates machine-learning models by leveraging several graph-level transformations and optimizations. These optimizations include:
 
-Our documentation is structured as follows:
+* Operator fusion
+* Arithmetic simplifications
+* Dead-code elimination
+* Common subexpression elimination (CSE)
+* Constant propagation
+
+After optimization, MIGraphX generates code for AMD GPUs by calling various ROCm libraries to create the fastest combinations of HIP kernels.
+
+The MIGraphX public repository is located at `https://github.com/ROCm/AMDMIGraphX/ <https://github.com/ROCm/AMDMIGraphX/>`_
 
 .. grid:: 2
   :gutter: 3
 
-  .. grid-item-card:: Reference
+  .. grid-item-card:: Install
+
+    * :doc:`Installing MIGraphX <./install/installing_with_package>`
+
+  .. grid-item-card:: Using the MIGraphX API
 
     * :ref:`cpp-api-reference`
     * :ref:`python-api-reference`
     * :ref:`migraphx-driver`
    
-  .. grid-item-card:: Contribution
+  .. grid-item-card:: Contributing to the MIGraphX code base
 
-    * :ref:`contributing-to-migraphx`
+    * :doc:`Building MIGraphX <./install/building_migraphx>`
+    * :doc:`Developing for MIGraphX <./dev/contributing-to-migraphx>` 
 
 To contribute to the documentation refer to
-`Contributing to ROCm  <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
+`Contribute to ROCm documentation <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
 
 Licensing information can be found on the
 `Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
-
-Index and search
-==================
-
-* :ref:`genindex`
-* :ref:`search`
diff --git a/docs/install/build_and_install_with_cmake.rst b/docs/install/build_and_install_with_cmake.rst
@@ -0,0 +1,62 @@
+.. meta::
+  :description: Build and install MIGraphX using CMake
+  :keywords: build, install, MIGraphX, AMD, ROCm, CMake
+
+********************************************************************
+Build and install MIGraphX using CMake
+********************************************************************
+
+ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.
+
+.. note::
+  
+  This method for building MIGraphX requires using ``sudo``.
+
+
+1. Install the dependencies:
+
+    .. code:: shell
+    
+        sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
+
+    .. note:: 
+
+        If ``rbuild`` is not installed on your system, install it with:
+
+            .. code:: shell
+
+                pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
+
+2. Create a build directory and change directory to it:
+
+    .. code:: shell
+
+        mkdir build
+        cd build
+
+3. Configure CMake:
+
+    .. code:: shell
+    
+        CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
+    
+4. Build MIGraphX source code:
+
+    .. code:: shell
+
+        make -j$(nproc)
+
+
+    You can verify this using:
+
+    .. code:: shell
+
+        make -j$(nproc) check
+    
+
+5. Install MIGraphX libraries:
+
+    .. code:: shell
+
+        make install
+    
diff --git a/docs/install/build_and_install_with_docker.rst b/docs/install/build_and_install_with_docker.rst
@@ -0,0 +1,52 @@
+.. meta::
+  :description: Installing MIGraphX using Docker
+  :keywords: install, MIGraphX, AMD, ROCm, Docker
+
+********************************************************************
+Installing MIGraphX using Docker
+********************************************************************
+
+ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.
+
+.. note::
+  
+  Docker commands are run using ``sudo``. 
+
+1. Build the Docker image. This command will install all the prerequisites required to install MIGraphX. Ensure that you are running this in the same directory as ``Dockerfile``. 
+
+    .. code:: shell
+    
+      sudo docker build -t migraphx .
+  
+
+2. Create and run the container. Once this command is run, you will be in the ``/code/AMDMIGraphX`` directory of a pseudo-tty.
+
+    .. code:: shell
+    
+      sudo docker run --device='/dev/kfd' --device='/dev/dri' -v=`pwd`:/code/AMDMIGraphX -w /code/AMDMIGraphX --group-add video -it migraphx
+
+3. In the ``/code/AMDMIGraphX``, create a ``build`` directory, then change directory to ``/code/AMDMIGraphX/build``:
+
+    .. code:: shell
+
+      mkdir build
+      cd build
+
+
+4. Configure CMake:
+
+    .. code:: shell
+
+      CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
+  
+4. Build the MIGraphX libraries:
+
+    .. code:: shell
+    
+      make -j$(nproc)
+
+5. Install the libraries:
+
+    .. code:: shell
+
+      make install
diff --git a/docs/install/build_and_install_with_rbuild.rst b/docs/install/build_and_install_with_rbuild.rst
@@ -0,0 +1,32 @@
+.. meta::
+  :description: Build and install MIGraphX using rbuild
+  :keywords: build, install, MIGraphX, AMD, ROCm, rbuild
+
+********************************************************************
+Build and install MIGraphX using rbuild
+********************************************************************
+
+ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.
+
+.. note::
+  
+  This method for building MIGraphX requires using ``sudo``.
+
+1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`:
+
+    .. code:: shell
+
+        sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
+    
+2. Install `rbuild <https://github.com/RadeonOpenCompute/rbuild>`_:
+
+    .. code:: shell
+
+        pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
+    
+
+3. Build MIGraphX source code:
+
+    .. code:: shell
+
+        sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
diff --git a/docs/install/building_migraphx.rst b/docs/install/building_migraphx.rst
@@ -0,0 +1,32 @@
+.. meta::
+  :description: Build and install MIGraphX
+  :keywords: build, install, MIGraphX, AMD, ROCm, rbuild, development, contributing
+
+********************************************************************
+Building MIGraphX
+********************************************************************
+
+ROCm must be installed prior to building MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on ROCm installation on Linux.
+
+.. note::
+  
+  This method for building MIGraphX requires using ``sudo``.
+
+1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`:
+
+    .. code:: shell
+
+        sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
+    
+2. Install `rbuild <https://github.com/RadeonOpenCompute/rbuild>`_:
+
+    .. code:: shell
+
+        pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
+    
+
+3. Build MIGraphX source code:
+
+    .. code:: shell
+
+        sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
diff --git a/docs/install/installing_with_package.rst b/docs/install/installing_with_package.rst
@@ -0,0 +1,21 @@
+.. meta::
+  :description: Installing MIGraphX using the package installer
+  :keywords: install, MIGraphX, AMD, ROCm, package installer
+
+********************************************************************
+Installing MIGraphX
+********************************************************************
+
+ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.
+
+Installing MIGraphX using the package installer is sufficient for users who want to use the MIGraphX API.
+
+If you want to develop for MIGraphX and contribute to the source code, see `Building MIGraphX <https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/install/docs/install/building_migraphx.html>`_ and `Developing for MIGraphX <https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/dev/contributing-to-migraphx.html>`_
+
+The package installer will install all the prerequisites needed for MIGraphX.
+
+Use the following command to install MIGraphX: 
+
+  .. code:: shell
+  
+    sudo apt update && sudo apt install -y migraphx
diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in
diff --git a/docs/what-is-migraphx.rst b/docs/what-is-migraphx.rst
