Documentation updates for Read the Docs

Docsupdate (#1748)
Co-authored-by: Sam Wu <sam.wu2@amd.com>
Co-authored-by: Paul <pfultz2@yahoo.com>

rocm-docs-core v0.13.4

fix licensing for actions

doc/src/dev/tools.rst → docs/dev/tools.rst

@@ -53,11 +53,11 @@ Average total time is also provided. There are three files provided for referenc
 
 An example output:
 
-.. image:: ./roctx1.jpg
+.. image:: ../data/roctx1.jpg
 
 Hotspot kerel timing information:
 
-.. image:: ./roctx2.jpg
+.. image:: ../data/roctx2.jpg
 
 **Parsing an already existing JSON file:**
 ::

docs/dev_intro.rst

+MIGraphX Fundamentals
+======================
+
+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``.
+
+
+Location of the Examples
+-------------------------
+
+The ``ref_dev_examples.cpp`` can be found in the test directory (``/test``).
+The executable file ``test_ref_dev_examples`` based on this file will be created in the ``bin/`` of the build directory after running ``make -j$(nproc) test_ref_dev_examples``.
+The executable will also be created when running ``make -j$(nproc) check``, alongside with all the other tests.
+Directions for building MIGraphX from source can be found in the main README file: ``https://github.com/ROCmSoftwarePlatform/AMDMIGraphX#readme``.
+
+
+Adding Two Literals
+--------------------
+
+A program is a collection of modules, which are collections of instructions to be executed when calling `eval <migraphx::program::eval>`.
+Each instruction has an associated `operation <migraphx::operation>` which represents the computation to be performed by the instruction.
+
+We start with a snippet of the simple ``add_two_literals()`` function::
+
+    // create the program and get a pointer to the main module
+    migraphx::program p;
+    auto* mm = p.get_main_module();
+
+    // add two literals to the program
+    auto one = mm->add_literal(1);
+    auto two = mm->add_literal(2);
+
+    // make the add operation between the two literals and add it to the program
+    mm->add_instruction(migraphx::make_op("add"), one, two);
+
+    // compile the program on the reference device
+    p.compile(migraphx::ref::target{});
+
+    // evaulate the program and retreive the result
+    auto result = p.eval({}).back();
+    std::cout << "add_two_literals: 1 + 2 = " << result << "\n";
+
+We start by creating a simple ``migraphx::program`` object and then getting a pointer to the main module of it.
+The program is a collection of ``modules`` that start executing from the main module, so instructions are added to the modules rather than directly onto the program object.
+We then use the `add_literal <migraphx::program::add_literal>` function to add an instruction that stores the literal number ``1`` while returning an `instruction_ref <migraphx::instruction_ref>`.
+The returned `instruction_ref <migraphx::instruction_ref>` can be used in another instruction as an input.
+We use the same `add_literal <migraphx::program::add_literal>` function to add a ``2`` to the program.
+After creating the literals, we then create the instruction to add the numbers together.
+This is done by using the `add_instruction <migraphx::program::add_instruction>` function with the ``"add"`` `operation <migraphx::program::operation>` created by `make_op <migraphx::program::make_op>` along with the previous `add_literal` `instruction_ref <migraphx::instruction_ref>` for the input arguments of the instruction.
+Finally, we can run this `program <migraphx::program>` by compiling it for the reference target (CPU) and then running it with `eval <migraphx::program::eval>`
+The result is then retreived and printed to the console.
+
+We can compile the program for the GPU as well, but the file will have to be moved to the ``test/gpu/`` directory and the correct target must be included::
+
+    #include <migraphx/gpu/target.hpp>
+
+
+Using Parameters
+-----------------
+
+The previous program will always produce the same value of adding ``1`` and ``2``.
+In the next program we want to pass an input to a program and compute a value based on the input.
+We can modify the program to take an input parameter ``x``, as seen in the ``add_parameter()`` function::
+
+    migraphx::program p;
+    auto* mm = p.get_main_module();
+    migraphx::shape s{migraphx::shape::int32_type, {1}};
+
+    // add a "x" parameter with the shape s
+    auto x   = mm->add_parameter("x", s);
+    auto two = mm->add_literal(2);
+
+    // add the "add" instruction between the "x" parameter and "two" to the module
+    mm->add_instruction(migraphx::make_op("add"), x, two);
+    p.compile(migraphx::ref::target{});
+
+This adds a parameter of type ``int32``, and compiles it for the CPU.
+To run the program, we need to pass the parameter as a ``parameter_map`` when we call `eval <migraphx::program::eval>`.
+We create the ``parameter_map`` by setting the ``x`` key to an `argument <migraphx::argument>` object with an ``int`` data type::
+
+    // create a parameter_map object for passing a value to the "x" parameter
+    std::vector<int> data = {4};
+    migraphx::parameter_map params;
+    params["x"] = migraphx::argument(s, data.data());
+
+    auto result = p.eval(params).back();
+    std::cout << "add_parameters: 4 + 2 = " << result << "\n";
+    EXPECT(result.at<int>() == 6);
+
+
+Handling Tensor Data
+---------------------
+
+In the previous examples we have only been dealing with scalars, but the `shape <migraphx::shape>` class can describe multi-dimensional tensors.
+For example, we can compute a simple convolution::
+
+    migraphx::program p;
+    auto* mm = p.get_main_module();
+
+    // create shape objects for the input tensor and weights
+    migraphx::shape input_shape{migraphx::shape::float_type, {2, 3, 4, 4}};
+    migraphx::shape weights_shape{migraphx::shape::float_type, {3, 3, 3, 3}};
+
+    // create the parameters and add the "convolution" operation to the module
+    auto input   = mm->add_parameter("X", input_shape);
+    auto weights = mm->add_parameter("W", weights_shape);
+    mm->add_instruction(migraphx::make_op("convolution", {{"padding", {1, 1}}, {"stride", {2, 2}}}), input, weights);
+
+Here we create two parameters for both the ``input`` and ``weights``.
+In the previous examples, we created simple literals, however, most programs will take data from allocated buffers (usually on the GPU).
+In this case, we can create `argument <migraphx::argument>` objects directly from the pointers to the buffers::
+
+    // Compile the program
+    p.compile(migraphx::ref::target{});
+
+    // Allocated buffers by the user
+    std::vector<float> a = ...;
+    std::vector<float> c = ...;
+
+    // Solution vector
+    std::vector<float> sol = ...;
+
+    // Create the arguments in a parameter_map
+    migraphx::parameter_map params;
+    params["X"] = migraphx::argument(input_shape, a.data());
+    params["W"] = migraphx::argument(weights_shape, c.data());
+
+    // Evaluate and confirm the result
+    auto result = p.eval(params).back();
+    std::vector<float> results_vector(64);
+    result.visit([&](auto output) { results_vector.assign(output.begin(), output.end()); });
+
+    EXPECT(migraphx::verify_range(results_vector, sol));
+
+An `argument <migraphx::argument>` can handle memory buffers from either the GPU or the CPU.
+By default when running the `program <migraphx::program>`, buffers are allocated on the corresponding target.
+When compiling for the CPU, the buffers by default will be allocated on the CPU.
+When compiling for the GPU, the buffers by default will be allocated on the GPU.
+With the option ``offloaf_copy=true`` set while compiling for the GPU, the buffers will be located on the CPU.
+
+
+Importing From ONNX
+--------------------
+
+A `program <migraphx::program>` can be built directly from an onnx file using the MIGraphX ONNX parser.
+This makes it easier to use neural networks directly from other frameworks.
+In this case, there is an ``parse_onnx`` function::
+
+    program p = migraphx::parse_onnx("model.onnx");
+    p.compile(migraphx::gpu::target{});
+

docs/developer_guide.rst

+Developer Guide
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   dev/data
+   dev/operators
+   dev/program
+   dev/targets
+   dev/quantization
+   dev/pass
+   dev/matchers
+   dev/tools

doc/src/index.rst → docs/index.rst

@@ -3,18 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to AMD MIGraphX's documentation!
-========================================
-
-.. toctree::
-   :maxdepth: 3
-   :caption: Contents:
-
-   py_user_guide
-   cpp_user_guide
-   driver
-   developer_guide
+AMD MIGraphX documentation
+==========================
 
+AMD MIGraphX is AMD's graph inference engine that accelerates machine learning model inference. 
 
 Indices and tables
 ==================