[docs] Improve readability of ROCprofiler-SDK API library documentation (#359)

* Use custom .rst to make api doc more readable.

* Update index.rst

* Misc docs updates

- doxygen source code fixes
- updated doxygen files
- fixed conf.py (does not generate code in source tree)

* Update source/docs/api-reference/rocprofiler-sdk_api_reference.rst

Co-authored-by: Rawat, Swati <Swati.Rawat@amd.com>

* Update source/docs/api-reference/rocprofiler-sdk_api_reference.rst

Co-authored-by: Rawat, Swati <Swati.Rawat@amd.com>

* Update source/docs/api-reference/rocprofiler-sdk_api/modules.rst

Co-authored-by: Rawat, Swati <Swati.Rawat@amd.com>

* Update source/docs/api-reference/rocprofiler-sdk_api/global_data_structures_topics_files.rst

Co-authored-by: Rawat, Swati <Swati.Rawat@amd.com>

* Duplicate

* test warnings

* Update CMakeLists.txt

* Update rocprofiler-sdk.dox.in

* Update update-docs.sh

* fix docs build failures by -q -T flags.

* set warn_as_error to NO.

* test -W to suppress warnings.

* remove -q flag from make.

* reduce dot graph depth to 100

* Update custom docs target

- docs target is now no longer part of the dependency list for the all target
- installation of docs requires explicitly building the docs target (i.e. OPTIONAL install of _build/html/ folder)

* add quit and trace mode back.

* increase DOT_GRAPH_MAX_NODES to 500 back.

* Format.

---------

Co-authored-by: Venkateshwar Reddy Kandula <vkandula@amd.com>
Co-authored-by: Jonathan R. Madsen <jonathanrmadsen@gmail.com>
Co-authored-by: Bhardwaj, Gopesh <Gopesh.Bhardwaj@amd.com>
Co-authored-by: Rawat, Swati <Swati.Rawat@amd.com>
Co-authored-by: Madsen, Jonathan <Jonathan.Madsen@amd.com>

source/include/rocprofiler-sdk/experimental/counters.h

@@ -30,7 +30,7 @@ ROCPROFILER_EXTERN_C_INIT
 
 /**
  * @brief (experimental) Apply a custom counter definition (YAML). This function must be called
- * before counter iteration functions like @ref rocprofiler_iterate_agent_supported_counters if
+ * before counter iteration functions like ::rocprofiler_iterate_agent_supported_counters if
  * custom counter definitions are to be used. This function will return an error if the definition
  * has already been loaded.
  * @param [in] yaml YAML string containing counter definitions
@@ -46,6 +46,4 @@ rocprofiler_load_counter_definition(const char*                yaml,
                                     size_t                     size,
                                     rocprofiler_counter_flag_t flags) ROCPROFILER_API;
 
-/** @} */
-
 ROCPROFILER_EXTERN_C_FINI

source/include/rocprofiler-sdk/experimental/thread-trace/core.h

@@ -36,6 +36,10 @@ ROCPROFILER_EXTERN_C_INIT
  * @{
  */
 
+/**
+ * @brief Types of ATT parameters
+ *
+ */
 typedef enum rocprofiler_att_parameter_type_t
 {
     ROCPROFILER_ATT_PARAMETER_TARGET_CU = 0,       ///< Select the Target CU or WGP
@@ -48,6 +52,10 @@ typedef enum rocprofiler_att_parameter_type_t
     ROCPROFILER_ATT_PARAMETER_LAST
 } rocprofiler_att_parameter_type_t;
 
+/**
+ * @brief ATT parameter specification
+ *
+ */
 typedef struct rocprofiler_att_parameter_t
 {
     rocprofiler_att_parameter_type_t type;
@@ -64,6 +72,7 @@ typedef struct rocprofiler_att_parameter_t
 
 /**
  * @brief Callback to be triggered every time some ATT data is generated by the device
+ * @param [in] agent Identifier for the target agent (@see ::rocprofiler_agent_id_t)
  * @param [in] shader_engine_id ID of shader engine, as enabled by SE_MASK
  * @param [in] data Pointer to the buffer containing the ATT data
  * @param [in] data_size Number of bytes in "data"