Port hipcc doc reorg to docs/6.2.0 (#130)

* hipcc docs update

* minor edit

* remove note about llvm

* fix syntax

* Conditionally skip docs PR build

If there is no change to the docs folder or RTD YAML
compared to the amd-staging branch

---------

Co-authored-by: randyh62 <randyh@amd.com>
Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com>

Author: 3 people

amd/hipcc/.readthedocs.yaml

@@ -16,3 +16,16 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+  jobs:
+    post_checkout:
+    # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs build.
+    #
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/amd-staging -- docs/ .readthedocs.yaml;
+      then
+        exit 183;
+      fi

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

@@ -1,13 +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: About
-    entries:
-    - file: license
+
+- caption: Install
+  entries:
+  - file: build
+  - file: env
+
+- caption: How to
+  entries:
+  - file: usage
+
+- caption: About
+  entries:
+  - file: license.md

amd/hipcc/docs/index.md

@@ -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
+

amd/hipcc/docs/index.rst

@@ -16,3 +16,16 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+  jobs:
+    post_checkout:
+    # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs build.
+    #
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/amd-staging -- docs/ .readthedocs.yaml;
+      then
+        exit 183;
+      fi