ROCTx Documentation (#29)

* Add roctx doc

* Add roctx doxyfile input

* Update links and toc

* Build doxysphinx for both doxygen files

* Update scripts

* Generate roctx doxygen files

* Change doxygen path

to allow for 2 doxyfiles

* Make doxygen dir for script

* Call make _doxygen dir with p flag

* Create _doxygen dir in workfllow

* Create doc dirs for doxygen

* Run update docs as sudo

* Fix typo in mkdir command

* Include graphviz for dot

* Install dot for docs CI

* Install dot as sudo due to permission denied

* Install doxygen via sudo

* Install doxysphinx

* Add postcheckout step to RTD to config and gen doxygen docs

* On RTD, update doxygen after creating env

* update docs.yml

* update docs.yml

* fixing build-docs-from-source

* Fixing build docs from source

* update docs.yml

* trying to fix readthedocs

* trying to fix readthedocs

* update docs.yml

* improve mainpage documentation

* update docs

* clang-format fix

---------

Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com>
Co-authored-by: Madsen, Jonathan <Jonathan.Madsen@amd.com>

source/include/rocprofiler-sdk-roctx/roctx.h

@@ -22,16 +22,50 @@
 
 #pragma once
 
-/** \mainpage ROCTx API Specification
+/**
+ * \file roctx.h
+ * \brief ROCTx API interface for AMD code annotation and profiling
+ *
+ * \mainpage ROCTx API Specification
  *
  * \section introduction Introduction
- * ROCTx is a library that implements the AMD code annotation API.  It provides
- * the support necessary to annotate events and code ranges in applications.
- */
-
-/**
- * \file
- * ROCTx API interface.
+ * ROCTx is a comprehensive library that implements the AMD code annotation API. It provides
+ * essential functionality for:
+ * - Event annotation and marking
+ * - Code range tracking and management
+ * - Profiler control and customization
+ * - Thread and device naming capabilities
+ *
+ * Key features:
+ * - Nested range tracking with push/pop functionality
+ * - Process-wide range management
+ * - Thread-specific and global profiler control
+ * - Device and stream naming support
+ * - HSA agent and HIP device management
+ *
+ * The API is divided into several main components:
+ * 1. Markers - For single event annotations
+ * 2. Ranges - For tracking code execution spans
+ * 3. Profiler Control - For managing profiling tool behavior
+ * 4. Naming Utilities - For labeling threads, devices, and streams
+ *
+ * Thread Safety:
+ * - Range operations are thread-local and thread-safe
+ * - Marking operations are thread-safe
+ * - Profiler control operations are process-wide
+ *
+ * Integration:
+ * - Compatible with HIP runtime
+ * - Supports HSA (Heterogeneous System Architecture)
+ * - Provides both C and C++ interfaces
+ *
+ * Performance Considerations:
+ * - Minimal overhead for marking and range operations
+ * - Thread-local storage for efficient range stacking
+ * - Lightweight profiler control mechanisms
+ *
+ * \note All string parameters must be null-terminated
+ * \warning Proper nesting of range push/pop operations is user's responsibility
  */
 
 #include <stddef.h>

source/include/rocprofiler-sdk/rocprofiler.h

@@ -22,6 +22,34 @@
 
 #pragma once
 
+/**
+ *
+ * \file rocprofiler.h
+ * \brief ROCProfiler-SDK API interface.
+ *
+ * \mainpage ROCProfiler-SDK API Specification
+ *
+ * \section introduction Introduction
+ * ROCprofiler-SDK is a library that implements the profiling and performance monitoring
+ * capabilities for AMD's ROCm platform. It provides a comprehensive set of APIs for:
+ *
+ * - Hardware performance counters monitoring
+ * - PC sampling for kernel execution analysis
+ * - Buffer and callback-based tracing mechanisms
+ * - Device and dispatch counting services
+ * - External correlation tracking
+ * - HIP and HSA runtime profiling support
+ *
+ * The library is designed to help developers analyze and optimize the performance
+ * of applications running on AMD GPUs. It offers both low-level hardware access
+ * and high-level profiling abstractions to accommodate different profiling needs.
+ *
+ *
+ * \section compatibility Compatibility
+ * ROCprofiler-SDK is compatible with AMD ROCm platform and supports
+ * profiling of applications using HIP and HSA runtimes.
+ */
+
 #include <stddef.h>
 #include <stdint.h>