Port HIPCC doc reorg to 6.1.1 (#94)

* Apply and standardize Read the Docs documentation for HIPCC

Relates to #12

Relates to ROCm/rocm-docs-core#330

Change-Id: Ic6a67f6edb21898c2ac8cf1dce91e94c507af4ad

* SWDEV-385160 - clean up references to Environment Variables

Change-Id: I2d1581cda76aa48a46e1f0a173a963c16fe9a36b

* hipcc docs update

* minor edit

* remove note about llvm

* fix syntax

---------

Co-authored-by: Sam Wu <[email protected]>
Co-authored-by: David Salinas <[email protected]>
Co-authored-by: randyh62 <[email protected]>

Author: 4 people

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/amd/hipcc/docs/sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    labels:
+      - "documentation"
+    reviewers:
+      - "samjwu"

amd/hipcc/README.md

@@ -5,46 +5,63 @@
 <!-- toc -->
 
 - [hipcc](#hipcc)
-     * [Documentation](#documentation)
-     * [Environment Variables](#envVar)
-     * [Usage](#hipcc-usage)
-     * [Building](#building)
-     * [Testing](#testing)
+  - [Documentation](#documentation)
+  - [Environment Variables](#envVar)
+  - [Usage](#usage)
+  - [Building](#building)
+  - [Testing](#testing)
 
 <!-- tocstop -->
 
 ## <a name="hipcc"></a> hipcc
 
-`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. Historically, `hipcc` was provided as a script in the HIP repo ( https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc ). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo.
+`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. 
 
 `hipcc` will pass-through options to the target compiler. The tools calling hipcc must ensure the compiler options are appropriate for the target compiler.
 
+### <a name="building"></a> Building
+
+Building on Linux:
+
+```bash
+mkdir build
+cd build
+
+cmake ..
+
+make -j4
+```
+
+The hipcc and hipconfig executables are created in the current build folder. 
+You may also create installable packages with :
+```bash
+make package
+```
+
 ## Documentation
 
 Run the steps below to build documentation locally.
 
-```
+```shell
 cd docs
 
-pip3 install -r .sphinx/requirements.txt
+pip3 install -r sphinx/requirements.txt
 
 python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
 ```
 
 ### <a name="envVar"></a> Environment Variables
 
 The environment variable HIP_PLATFORM may be used to specify amd/nvidia:
+
 - HIP_PLATFORM='amd' or HIP_PLATFORM='nvidia'.
 - If HIP_PLATFORM is not set, then hipcc will attempt to auto-detect based on if nvcc is found.
 
 Other environment variable controls:
-- HIP_PATH        : Path to HIP directory, default is one dir level above location of hipcc.
+
 - CUDA_PATH       : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only.
-- HSA_PATH        : Path to HSA dir (defaults to ../../hsa relative to abs_path of hipcc). Used on AMD platforms only.
-- HIP_ROCCLR_HOME : Path to HIP/ROCclr directory. Used on AMD platforms only.
-- HIP_CLANG_PATH  : Path to HIP-Clang (default to ../../llvm/bin relative to hipcc's abs_path). Used on AMD platforms only.
 
-### <a name="usage"></a> hipcc: usage
+### <a name="usage"></a> Usage
 
 The built executables can be used the same way as the hipcc/hipconfig perl scripts. 
 To use the newly built executables from the build folder use ./ in front of the executable name -
@@ -56,22 +73,6 @@ Example:
 ./hipconfig --full
 ```
 
-when the excutables are copied to /opt/rocm/hip/bin or <anyfolder>hip/bin. 
-The ./ is not required as the HIP path is added to the envirnoment variables list.
-
-### <a name="building"></a> hipcc: building
-
-```bash
-mkdir build
-cd build
-
-cmake ..
-
-make -j
-```
-
-The hipcc and hipconfig executables are created in the current build folder. These executables need to be copied to /opt/rocm/hip/bin folder location. Packaging and installing will be handled in future releases.
-
 ### <a name="testing"></a> hipcc: testing
 
-Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Separate tests for hipcc/hipconfig is currently not planned.   
+Currently hipcc/hipconfig executables are tested by building and executing HIP tests: https://github.com/ROCm/hip-tests

amd/hipcc/docs/build.md

@@ -0,0 +1,28 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_build:
+
+******************************************
+Building and testing HIPCC
+******************************************
+
+To build the ``hipcc`` and ``hipconfig`` executables, use the following commands. 
+
+.. code-block:: bash
+
+    mkdir build
+    cd build
+
+    cmake ..
+
+    make -j
+
+.. note::
+  The tools are created in the current build folder, and will need to be copied to ``/opt/rocm/hip/bin`` folder location.
+
+Testing HIPCC
+=============
+
+Currently ``hipcc`` and ``hipconfig`` tools are tested by building and running test samples that can be found at `HIP-tests <https://github.com/ROCm/hip-tests/tree/develop/samples>`_. 

amd/hipcc/docs/build.rst

@@ -0,0 +1,20 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_vars:
+
+******************************************
+HIPCC environment variables
+******************************************
+
+The environment variable ``HIP_PLATFORM`` can be used to specify ``amd`` or ``nvidia`` depending on the available backend tool flows:
+
+* ``HIP_PLATFORM`` = ``amd`` or ``HIP_PLATFORM`` = ``nvidia``
+
+.. note:: 
+    If ``HIP_PLATFORM`` is not set, then ``hipcc`` will attempt to auto-detect based on if the ``nvcc`` tool is found.
+
+Additional environment variable controls:
+
+* ``CUDA_PATH``       : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms.

amd/hipcc/docs/env.md

@@ -0,0 +1,34 @@
+.. meta::
+  :description: HIPCC command
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc-docs:
+
+******************************************
+HIPCC documentation
+******************************************
+
+``hipcc`` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. 
+
+There is both a Perl version, and a C++ executable version of the ``hipcc`` and ``hipconfig`` compiler driver utilities provided. By default the Perl version is used when ``hipcc`` is run. To enable the C++ versions, set the environment variable ``HIP_USE_PERL_SCRIPTS=0``.
+
+
+The documentation is structured as follows:
+
+.. grid:: 2
+  :gutter: 3
+
+  .. grid-item-card:: Installation
+
+    * :ref:`hipcc_build`
+    * :ref:`hipcc_vars`
+
+  .. grid-item-card:: How to
+
+    * :ref:`hipcc_use`
+
+To contribute to the documentation, refer to
+`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
+
+You can find licensing information on the
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

amd/hipcc/docs/env.rst

@@ -0,0 +1,4 @@
+# License
+
+```{include} ../LICENSE.txt
+```

amd/hipcc/docs/index.md

@@ -1,10 +1,20 @@
 # Anywhere {branch} is used, the branch name will be substituted.
 # These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
 root: index
 subtrees:
-  - numbered: False
-    entries:
-    - file: env
-    - file: usage
-    - file: build
-    - file: test
+
+- caption: Install
+  entries:
+  - file: build
+  - file: env
+
+- caption: How to
+  entries:
+  - file: usage
+
+- caption: About
+  entries:
+  - file: license.md

amd/hipcc/docs/index.rst

@@ -0,0 +1,21 @@
+.. meta::
+  :description: HIPCC environment variables
+  :keywords: HIPCC, ROCm, HIP tools, HIP compiler
+
+.. _hipcc_use:
+
+******************************************
+Using HIPCC
+******************************************
+
+The built executables can be used the same way as the ``hipcc`` and ``hipconfig`` Perl scripts. 
+To use the newly built executables from the build folder use ``./`` in front of the executable name. 
+For example:
+
+.. code-block:: shell
+
+    ./hipconfig --help
+    ./hipcc --help
+    ./hipcc --version
+    ./hipconfig --full
+