Docs skeleton (#51)

* Add doxygen-awesome-css submodule * Basic documentation files - conf.py: run by sphinx - about.md: info about rocprofiler - features.md: overview of features - installation.md: build/test/install instructions - index.md: sets up main page - generate-doxyfile.cmake: generates rocprofiler.dox with rocprofiler-specific info - environment.yml: conda environment - Makefile: sphinx makefile - README.md: build instructions - rocprofiler.dox.in: doxygen template - .gitignore: ignores generated files - .nojekyll: prevents GitHub Pages from using Jekyll for deployment of pages * Documentation scripts - scripts for doing common sequences of commands for building docs - update-docs.sh: builds the docs and installs the docs if /docs directory is present - update-doxygen.sh: quick script for generating doxygen * Workflow for docs - step for building docs - step for deploying docs * Update doxygen comments in include/rocprofiler - rocprofiler.h / rocprofiler_plugins.h - fixed non-existent global references in doxygen comments - fixed parameter names that were incorrect or not updated * Update docs workflow - only deploy docs when on main branch
2023-09-12 12:34:36 -05:00
@@ -0,0 +1,74 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - '*.md'
+      - 'source/docs/**'
+      - 'source/scripts/update-docs.sh'
+      - '.github/workflows/docs.yml'
+      - 'VERSION'
+  pull_request:
+    branches: [main]
+    paths:
+      - '*.md'
+      - 'source/docs/**'
+      - 'source/scripts/update-docs.sh'
+      - '.github/workflows/docs.yml'
+      - 'VERSION'
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  GIT_DISCOVERY_ACROSS_FILESYSTEM: 1
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+            submodules: true
+      - name: Install Conda
+        uses: s-weigand/setup-conda@v1
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Create Docs Directory
+        run:
+          mkdir -p docs
+      - name: Update Docs
+        working-directory: source/docs
+        run: |
+          conda env create -n rocprofiler-docs -f environment.yml
+          source activate
+          conda activate rocprofiler-docs
+          ../scripts/update-docs.sh
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs
+
+  deploy-docs:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: build-docs
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
@@ -7,3 +7,6 @@
 [submodule "fmt"]
 	path = external/fmt
 	url = https://github.com/fmtlib/fmt.git
+[submodule "source/docs/doxygen-awesome-css"]
+	path = external/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
@@ -0,0 +1,5 @@
+/build*
+/_build
+/_doxygen
+/.gitinfo
+/rocprofiler.dox
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1,19 @@
+# ROCprofiler Documentation
+
+## Build Instructions
+
+1. Install conda
+    - `wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh`
+    - `bash miniconda.sh -b -p /opt/conda`
+    - `export PATH=${PATH}:/opt/conda`
+2. Install conda environment
+    - `source activate`
+    - `conda env create -n rocprofiler-docs -f environment.yml`
+    - `conda activate rocprofiler-docs`
+3. Build the docs
+    - `../scripts/update-docs.sh`
+    - HTML docs will be located in `_build/html`
+
+## Developer Information
+
+If you create a new page, add the name of the new markdown file (without extension) to the [index.md](index.md) file.
@@ -0,0 +1,11 @@
+# About
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+## Overview
+
+TODO: Overview of rocprofiler v2
@@ -0,0 +1,163 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+import subprocess as sp
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath(".."))
+
+
+def install(package):
+    sp.call([sys.executable, "-m", "pip", "install", package])
+
+
+# Check if we're running on Read the Docs' servers
+read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
+
+
+# -- Project information -----------------------------------------------------
+project = "rocprofiler"
+copyright = "2023, Advanced Micro Devices, Inc."
+author = "ROCm Developer Tools"
+
+project_root = os.path.normpath(os.path.join(os.getcwd(), "..", ".."))
+version = open(os.path.join(project_root, "VERSION")).read().strip()
+# The full version, including alpha/beta/rc tags
+release = version
+
+_docdir = os.path.realpath(os.getcwd())
+_srcdir = os.path.realpath(os.path.join(os.getcwd(), ".."))
+_sitedir = os.path.realpath(os.path.join(os.getcwd(), "..", "site"))
+_staticdir = os.path.realpath(os.path.join(_docdir, "_static"))
+_templatedir = os.path.realpath(os.path.join(_docdir, "_templates"))
+
+if not os.path.exists(_staticdir):
+    os.makedirs(_staticdir)
+
+if not os.path.exists(_templatedir):
+    os.makedirs(_templatedir)
+
+
+# -- General configuration ---------------------------------------------------
+
+install("sphinx_rtd_theme")
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_markdown_tables",
+    "recommonmark",
+    "sphinxcontrib.doxylink",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {".md": CommonMarkParser}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The master toctree document.
+master_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+
+default_role = None
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_theme_options = {
+    # "analytics_id": "G-...",  #  Provided by Google in your dashboard
+    "logo_only": False,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    # 'style_nav_header_background': 'white',
+    # Toc options
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+doxygen_root = "_doxygen"  # this is just a convenience variable
+doxylink = {
+    "demo": (  # "demo" is the role name that you can later use in sphinx to reference this doxygen documentation (see below)
+        f"{doxygen_root}/tagfile.xml",  # the first parameter of this tuple is the tagfile
+        f"{doxygen_root}/html",  # the second parameter of this tuple is a relative path pointing from
+        # sphinx output directory to the doxygen output folder inside the output
+        # directory tree.
+        # Doxylink will use the tagfile to get the html file name of the symbol you want
+        # to link and then prefix it with this path to generate html links (<a>-tags).
+    ),
+}
+
+from pygments.styles import get_all_styles
+
+# The name of the Pygments (syntax highlighting) style to use.
+styles = list(get_all_styles())
+preferences = ("emacs", "pastie", "colorful")
+for pref in preferences:
+    if pref in styles:
+        pygments_style = pref
+        break
+
+from recommonmark.transform import AutoStructify
+
+
+# app setup hook
+def setup(app):
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "auto_toc_tree_section": "Contents",
+            "enable_eval_rst": True,
+            "enable_auto_doc_ref": False,
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)
@@ -0,0 +1,12 @@
+# Developer API
+
+```eval_rst
+.. toctree::
+    :glob:
+    :maxdepth: 4
+
+    _doxygen/html/topics
+    _doxygen/html/files
+    _doxygen/html/annotated
+    _doxygen/html/classes
+```
@@ -0,0 +1,142 @@
+name: rocprofiler-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - _libgcc_mutex=0.1=conda_forge
+  - _openmp_mutex=4.5=2_gnu
+  - alabaster=0.7.13=pyhd8ed1ab_0
+  - atk-1.0=2.38.0=hd4edc92_1
+  - babel=2.12.1=pyhd8ed1ab_1
+  - brotli-python=1.1.0=py311hb755f60_0
+  - bzip2=1.0.8=h7f98852_4
+  - c-ares=1.19.1=hd590300_0
+  - ca-certificates=2023.7.22=hbcca054_0
+  - cairo=1.16.0=h0c91306_1017
+  - certifi=2023.7.22=pyhd8ed1ab_0
+  - charset-normalizer=3.2.0=pyhd8ed1ab_0
+  - cmake=3.27.4=hcfe8598_4
+  - colorama=0.4.6=pyhd8ed1ab_0
+  - commonmark=0.9.1=py_0
+  - docutils=0.18.1=py311h06a4308_3
+  - doxygen=1.9.8=h661eb56_0
+  - expat=2.5.0=hcb278e6_1
+  - font-ttf-dejavu-sans-mono=2.37=hab24e00_0
+  - font-ttf-inconsolata=3.000=h77eed37_0
+  - font-ttf-source-code-pro=2.038=h77eed37_0
+  - font-ttf-ubuntu=0.83=hab24e00_0
+  - fontconfig=2.14.2=h14ed4e7_0
+  - fonts-conda-ecosystem=1=0
+  - fonts-conda-forge=1=0
+  - freetype=2.12.1=hca18f0e_1
+  - fribidi=1.0.10=h36c2ea0_0
+  - future=0.18.3=pyhd8ed1ab_0
+  - gdk-pixbuf=2.42.10=h6b639ba_2
+  - gettext=0.21.1=h27087fc_0
+  - giflib=5.2.1=h0b41bf4_3
+  - graphite2=1.3.13=h58526e2_1001
+  - graphviz=8.1.0=h28d9a01_0
+  - gtk2=2.24.33=h90689f9_2
+  - gts=0.7.6=h977cf35_4
+  - harfbuzz=8.2.0=h3d44ed6_0
+  - icu=73.2=h59595ed_0
+  - idna=3.4=pyhd8ed1ab_0
+  - imagesize=1.4.1=pyhd8ed1ab_0
+  - importlib-metadata=6.8.0=pyha770c72_0
+  - jinja2=3.1.2=pyhd8ed1ab_1
+  - keyutils=1.6.1=h166bdaf_0
+  - krb5=1.21.2=h659d440_0
+  - ld_impl_linux-64=2.40=h41732ed_0
+  - lerc=4.0.0=h27087fc_0
+  - libcurl=8.2.1=hca28451_0
+  - libdeflate=1.18=h0b41bf4_0
+  - libedit=3.1.20191231=he28a2e2_2
+  - libev=4.33=h516909a_1
+  - libexpat=2.5.0=hcb278e6_1
+  - libffi=3.4.2=h7f98852_5
+  - libgcc-ng=13.2.0=h807b86a_0
+  - libgd=2.3.3=h74d50f4_7
+  - libglib=2.78.0=hebfc3b9_0
+  - libgomp=13.2.0=h807b86a_0
+  - libiconv=1.17=h166bdaf_0
+  - libjpeg-turbo=2.1.5.1=h0b41bf4_0
+  - libnghttp2=1.52.0=h61bc06f_0
+  - libnsl=2.0.0=h7f98852_0
+  - libpng=1.6.39=h753d276_0
+  - librsvg=2.56.3=h98fae49_0
+  - libsqlite=3.43.0=h2797004_0
+  - libssh2=1.11.0=h0841786_0
+  - libstdcxx-ng=13.2.0=h7e041cc_0
+  - libtiff=4.5.1=h8b53f26_1
+  - libtool=2.4.7=h27087fc_0
+  - libuuid=2.38.1=h0b41bf4_0
+  - libuv=1.46.0=hd590300_0
+  - libwebp=1.3.1=hbf2b3c1_0
+  - libwebp-base=1.3.1=hd590300_0
+  - libxcb=1.15=h0b41bf4_0
+  - libxml2=2.11.5=h232c23b_1
+  - libzlib=1.2.13=hd590300_5
+  - markdown=3.4.4=pyhd8ed1ab_0
+  - markupsafe=2.1.3=py311h459d7ec_0
+  - ncurses=6.4=hcb278e6_0
+  - openssl=3.1.2=hd590300_0
+  - packaging=23.1=pyhd8ed1ab_0
+  - pango=1.50.14=ha41ecd1_2
+  - pcre2=10.40=hc3806b6_0
+  - pip=23.2.1=pyhd8ed1ab_0
+  - pixman=0.40.0=h36c2ea0_0
+  - pthread-stubs=0.4=h36c2ea0_1001
+  - pygments=2.16.1=pyhd8ed1ab_0
+  - pysocks=1.7.1=pyha2e5f31_6
+  - python=3.11.5=hab00c5b_0_cpython
+  - python_abi=3.11=3_cp311
+  - pytz=2023.3.post1=pyhd8ed1ab_0
+  - readline=8.2=h8228510_1
+  - recommonmark=0.7.1=pyhd8ed1ab_0
+  - requests=2.31.0=pyhd8ed1ab_0
+  - rhash=1.4.4=hd590300_0
+  - setuptools=68.1.2=pyhd8ed1ab_0
+  - snowballstemmer=2.2.0=pyhd8ed1ab_0
+  - sphinx=7.2.5=pyhd8ed1ab_0
+  - sphinx-markdown-tables=0.0.17=pyh6c4a22f_0
+  - sphinx_rtd_theme=1.3.0=pyha770c72_0
+  - sphinxcontrib-applehelp=1.0.7=pyhd8ed1ab_0
+  - sphinxcontrib-devhelp=1.0.5=pyhd8ed1ab_0
+  - sphinxcontrib-htmlhelp=2.0.4=pyhd8ed1ab_0
+  - sphinxcontrib-jquery=4.1=pyhd8ed1ab_0
+  - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_0
+  - sphinxcontrib-qthelp=1.0.6=pyhd8ed1ab_0
+  - sphinxcontrib-serializinghtml=1.1.9=pyhd8ed1ab_0
+  - tk=8.6.12=h27826a3_0
+  - tzdata=2023c=h71feb2d_0
+  - urllib3=2.0.4=pyhd8ed1ab_0
+  - wheel=0.41.2=pyhd8ed1ab_0
+  - xorg-kbproto=1.0.7=h7f98852_1002
+  - xorg-libice=1.1.1=hd590300_0
+  - xorg-libsm=1.2.4=h7391055_0
+  - xorg-libx11=1.8.6=h8ee46fc_0
+  - xorg-libxau=1.0.11=hd590300_0
+  - xorg-libxdmcp=1.1.3=h7f98852_0
+  - xorg-libxext=1.3.4=h0b41bf4_2
+  - xorg-libxrender=0.9.11=hd590300_0
+  - xorg-renderproto=0.11.1=h7f98852_1002
+  - xorg-xextproto=7.3.0=h0b41bf4_1003
+  - xorg-xproto=7.0.31=h7f98852_1007
+  - xz=5.2.6=h166bdaf_0
+  - zipp=3.16.2=pyhd8ed1ab_0
+  - zlib=1.2.13=hd590300_5
+  - zstd=1.5.5=hfc55251_0
+  - pip:
+      - click==8.1.7
+      - click-log==0.4.0
+      - doxysphinx==3.3.4
+      - libsass==0.22.0
+      - lxml==4.9.3
+      - mpire==2.8.0
+      - pyjson5==1.6.4
+      - pyparsing==3.1.1
+      - python-dateutil==2.8.2
+      - six==1.16.0
+      - sphinx-markdown==1.0.2
+      - sphinxcontrib-doxylink==1.12.2
+      - tqdm==4.66.1
@@ -0,0 +1,11 @@
+# Features
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+## Overview
+
+TODO: Overview of rocprofiler v2 features
@@ -0,0 +1,19 @@
+if(NOT DEFINED SOURCE_DIR)
+    message(FATAL_ERROR "Please define SOURCE_DIR")
+endif()
+
+get_filename_component(SOURCE_DIR "${SOURCE_DIR}" ABSOLUTE)
+
+find_program(DOT_EXECUTABLE NAMES dot)
+
+if(NOT DOT_EXECUTABLE)
+    message(FATAL_ERROR "Please install dot and/or specify DOT_EXECUTABLE")
+endif()
+
+file(READ "${SOURCE_DIR}/VERSION" FULL_VERSION_STRING LIMIT_COUNT 1)
+string(REGEX REPLACE "(\n|\r)" "" FULL_VERSION_STRING "${FULL_VERSION_STRING}")
+string(REGEX REPLACE "([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*)" "\\1.\\2.\\3"
+                     ROCPROFILER_VERSION "${FULL_VERSION_STRING}")
+
+configure_file(${SOURCE_DIR}/source/docs/rocprofiler.dox.in
+               ${SOURCE_DIR}/source/docs/rocprofiler.dox @ONLY)
@@ -0,0 +1,13 @@
+# Welcome to the [ROCprofiler](https://github.com/ROCm-Developer-Tools/rocprofiler-v2-internal) Documentation!
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+   :caption: Table of Contents
+
+   about
+   features
+   installation
+   developer_api
+```
@@ -0,0 +1,50 @@
+# Installation
+
+```eval_rst
+.. toctree::
+   :glob:
+   :maxdepth: 4
+```
+
+## Quick Start (Latest Release, Binary Installer)
+
+TODO: Installation quick start
+
+## Operating System
+
+TODO: supported OSes
+
+### Identifying the Operating System
+
+If you are unsure of the operating system and version, the `/etc/os-release` and `/usr/lib/os-release` files contain
+operating system identification data for Linux systems.
+
+```shell
+$ cat /etc/os-release
+NAME="Ubuntu"
+VERSION="20.04.4 LTS (Focal Fossa)"
+ID=ubuntu
+...
+VERSION_ID="20.04"
+...
+```
+
+The relevent fields are `ID` and the `VERSION_ID`.
+
+## Installing ROCprofiler from source
+
+### Build Requirements
+
+TODO: build reqs
+
+### Building ROCprofiler
+
+TODO: cmake build
+
+### Testing ROCprofiler
+
+TODO: ctest
+
+### Installing ROCprofiler
+
+TODO: `make install` and/or `cpack`
@@ -0,0 +1,309 @@
+# Doxyfile 1.9.8
+
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = rocprofiler
+PROJECT_NUMBER = @ROCPROFILER_VERSION@
+PROJECT_BRIEF = "ROCm Profiling API and tools"
+PROJECT_LOGO =
+OUTPUT_DIRECTORY = _doxygen
+CREATE_SUBDIRS = NO
+ALLOW_UNICODE_NAMES = YES
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF =
+ALWAYS_DETAILED_SEC = YES
+INLINE_INHERITED_MEMB = YES
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = @SOURCE_DIR@/source/include @SOURCE_DIR@/source/lib
+STRIP_FROM_INC_PATH = @SOURCE_DIR@/source/include @SOURCE_DIR@/source/lib
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = NO
+JAVADOC_BANNER = NO
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = YES
+PYTHON_DOCSTRING = YES
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 4
+ALIASES =
+OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_JAVA = NO
+OPTIMIZE_FOR_FORTRAN = NO
+OPTIMIZE_OUTPUT_VHDL = NO
+OPTIMIZE_OUTPUT_SLICE = NO
+EXTENSION_MAPPING = hpp=C++ cpp=C++ hh=C++ cc=C++ h=C c=C py=Python
+MARKDOWN_SUPPORT = YES
+TOC_INCLUDE_HEADINGS = 2
+MARKDOWN_ID_STYLE = DOXYGEN
+AUTOLINK_SUPPORT = YES
+BUILTIN_STL_SUPPORT = YES
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+IDL_PROPERTY_SUPPORT = YES
+DISTRIBUTE_GROUP_DOC = NO
+GROUP_NESTED_COMPOUNDS = YES
+SUBGROUPING = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS = YES
+TYPEDEF_HIDES_STRUCT = YES
+LOOKUP_CACHE_SIZE = 5
+NUM_PROC_THREADS = 0
+TIMESTAMP = NO
+#---------------------------------------------------------------------------
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = NO
+EXTRACT_PRIV_VIRTUAL = NO
+EXTRACT_PACKAGE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = YES
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = NO
+HIDE_SCOPE_NAMES = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_HEADERFILE = YES
+SHOW_INCLUDE_FILES = YES
+SHOW_GROUPED_MEMB_INC = NO
+FORCE_LOCAL_INCLUDES = YES
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_MEMBERS_CTORS_1ST = YES
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+STRICT_PROTO_MATCHING = NO
+GENERATE_TODOLIST = NO
+GENERATE_TESTLIST = NO
+GENERATE_BUGLIST = NO
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_FILES = YES
+SHOW_NAMESPACES = YES
+FILE_VERSION_FILTER =
+LAYOUT_FILE =
+CITE_BIB_FILES =
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC = YES
+WARN_IF_UNDOC_ENUM_VAL = NO
+WARN_AS_ERROR = YES
+WARN_FORMAT = "---> WARNING! $file:$line: $text"
+WARN_LINE_FORMAT = "at line $line of file $file"
+# WARN_LOGFILE = doxy/warnings.log
+#---------------------------------------------------------------------------
+INPUT = @SOURCE_DIR@/README.md @SOURCE_DIR@/source/include/rocprofiler
+INPUT_ENCODING = UTF-8
+INPUT_FILE_ENCODING =
+FILE_PATTERNS = *.h *.hh *.hpp *.c *.cc *.cxx *.cpp *.c++ *.icc *.tcc conf.py
+RECURSIVE = YES
+EXCLUDE =
+EXCLUDE_SYMLINKS = YES
+EXCLUDE_PATTERNS = */.git/* @SOURCE_DIR@/samples/* @SOURCE_DIR@/**/tests/* @SOURCE_DIR@/source/include/rocprofiler/defines.h @SOURCE_DIR@/source/include/rocprofiler/config.h
+EXCLUDE_SYMBOLS = "std::*" "ROCPROFILER_ATTRIBUTE" "ROCPROFILER_API" "ROCPROFILER_NONNULL"
+EXAMPLE_PATH = @SOURCE_DIR@/samples
+EXAMPLE_PATTERNS = *.h *.hh *.hpp *.c *.cc *.cpp conf.py *.txt
+EXAMPLE_RECURSIVE = YES
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE = @SOURCE_DIR@/README.md
+FORTRAN_COMMENT_AFTER = 72
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = YES
+INLINE_SOURCES = YES
+STRIP_CODE_COMMENTS = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = YES
+IGNORE_PREFIX =
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_EXTRA_STYLESHEET = ../../external/doxygen-awesome-css/doxygen-awesome.css
+HTML_EXTRA_FILES =
+HTML_COLORSTYLE = LIGHT
+HTML_COLORSTYLE_HUE = 220
+HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_GAMMA = 80
+HTML_DYNAMIC_MENUS = YES
+HTML_DYNAMIC_SECTIONS = YES
+HTML_CODE_FOLDING = YES
+HTML_INDEX_NUM_ENTRIES = 1000
+GENERATE_DOCSET = NO
+DOCSET_FEEDNAME = "Doxygen generated docs"
+DOCSET_FEEDURL =
+DOCSET_BUNDLE_ID = org.doxygen.rocprofiler
+DOCSET_PUBLISHER_ID = org.doxygen.amd
+DOCSET_PUBLISHER_NAME = "AMD ROCm Developer Tools"
+GENERATE_HTMLHELP = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+CHM_INDEX_ENCODING =
+BINARY_TOC = NO
+TOC_EXPAND = YES
+SITEMAP_URL =
+GENERATE_QHP = NO
+QCH_FILE =
+QHP_NAMESPACE =
+QHP_VIRTUAL_FOLDER = doxy
+QHP_CUST_FILTER_NAME =
+QHP_CUST_FILTER_ATTRS =
+QHP_SECT_FILTER_ATTRS =
+QHG_LOCATION =
+GENERATE_ECLIPSEHELP = NO
+ECLIPSE_DOC_ID = org.doxygen.rocprofiler
+DISABLE_INDEX = NO
+GENERATE_TREEVIEW = YES
+FULL_SIDEBAR = NO
+ENUM_VALUES_PER_LINE = 1
+TREEVIEW_WIDTH = 300
+EXT_LINKS_IN_WINDOW = YES
+OBFUSCATE_EMAILS = YES
+HTML_FORMULA_FORMAT = png
+FORMULA_FONTSIZE = 12
+FORMULA_MACROFILE =
+USE_MATHJAX = NO
+MATHJAX_VERSION = MathJax_2
+MATHJAX_FORMAT = HTML-CSS
+MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS =
+MATHJAX_CODEFILE =
+SEARCHENGINE = NO
+SERVER_BASED_SEARCH = NO
+EXTERNAL_SEARCH = NO
+SEARCHENGINE_URL =
+SEARCHDATA_FILE = searchdata.xml
+EXTERNAL_SEARCH_ID =
+EXTRA_SEARCH_MAPPINGS =
+#---------------------------------------------------------------------------
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+LATEX_MAKEINDEX_CMD = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = 
+EXTRA_PACKAGES = float
+LATEX_HEADER =
+LATEX_FOOTER =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES =
+PDF_HYPERLINKS = YES
+USE_PDFLATEX = YES
+LATEX_BATCHMODE = YES
+LATEX_HIDE_INDICES = NO
+LATEX_BIB_STYLE = plain
+LATEX_EMOJI_DIRECTORY =
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_SUBDIR =
+MAN_LINKS = YES
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_PROGRAMLISTING = YES
+XML_NS_MEMB_FILE_SCOPE = YES
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK = NO
+DOCBOOK_OUTPUT = docbook
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+GENERATE_SQLITE3 = NO
+SQLITE3_OUTPUT = sqlite3
+SQLITE3_RECREATE_DB = YES
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = NO
+INCLUDE_PATH = @SOURCE_DIR@/source/include
+INCLUDE_FILE_PATTERNS = *.h
+PREDEFINED = "ROCPROFILER_API=" "ROCPROFILER_EXPORT=" "ROCPROFILER_IMPORT=" "ROCPROFILER_NONNULL(...)=" "__attribute__(x)=" "__declspec(x)=" "size_t=unsigned long" "uintptr_t=unsigned long" "DOXYGEN_SHOULD_SKIP_THIS=1"
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = NO
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE = _doxygen/tagfile.xml
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+EXTERNAL_PAGES = YES
+#---------------------------------------------------------------------------
+HIDE_UNDOC_RELATIONS = NO
+HAVE_DOT = YES
+DOT_NUM_THREADS = 0
+DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=12"
+DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=12"
+DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4"
+DOT_FONTPATH =
+CLASS_GRAPH = NO
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = YES
+UML_LIMIT_NUM_FIELDS = 10
+DOT_UML_DETAILS = NO
+DOT_WRAP_THRESHOLD = 17
+TEMPLATE_RELATIONS = YES
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DIR_GRAPH_MAX_DEPTH = 1
+DOT_IMAGE_FORMAT = svg
+INTERACTIVE_SVG = YES
+DOT_PATH = @DOT_EXECUTABLE@
+DOTFILE_DIRS =
+DIA_PATH =
+DIAFILE_DIRS =
+PLANTUML_JAR_PATH =
+PLANTUML_CFG_FILE =
+PLANTUML_INCLUDE_PATH =
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 0
+DOT_MULTI_TARGETS = YES
+GENERATE_LEGEND = YES
+#
+DOT_CLEANUP = YES
+MSCGEN_TOOL =
+MSCFILE_DIRS =
@@ -186,9 +186,9 @@ typedef struct
 */
 typedef enum
 {
-    ROCPROFILER_AGENT_TYPE_NONE = 0,  /// agent is unknown type
-    ROCPROFILER_AGENT_TYPE_CPU,       /// agent is CPU
-    ROCPROFILER_AGENT_TYPE_GPU,       /// agent is GPU
+    ROCPROFILER_AGENT_TYPE_NONE = 0,  ///< agent is unknown type
+    ROCPROFILER_AGENT_TYPE_CPU,       ///< agent is CPU
+    ROCPROFILER_AGENT_TYPE_GPU,       ///< agent is GPU
    ROCPROFILER_AGENT_TYPE_LAST,
 } rocprofiler_agent_type_t;

@@ -487,12 +487,12 @@ typedef struct
 * @brief API Tracing callback data.
 *
 * This can be casted to:
- *  ::rocprofiler_hsa_callback_data_t if the record kind is
- * ROCPROFILER_SERVICE_CALLBACK_TRACING_HSA_API
- *  ::rocprofiler_hip_callback_data_t if the record kind is
- * ROCPROFILER_SERVICE_CALLBACK_TRACING_HIP_API
- *  ::rocprofiler_marker_callback_data_t if the record kind is
- * ROCPROFILER_SERVICE_CALLBACK_TRACING_MARKER
+ *  rocprofiler_hsa_callback_data_t if the record kind is
+ * @ref ROCPROFILER_SERVICE_CALLBACK_TRACING_HSA_API
+ *  rocprofiler_hip_callback_data_t if the record kind is
+ * @ref ROCPROFILER_SERVICE_CALLBACK_TRACING_HIP_API
+ *  rocprofiler_marker_callback_data_t if the record kind is
+ * @ref ROCPROFILER_SERVICE_CALLBACK_TRACING_MARKER
 *
 */
 typedef void* rocprofiler_tracer_callback_data_t;
@@ -502,10 +502,10 @@ typedef void* rocprofiler_tracer_callback_data_t;
 *
 * Depending on the ::rocprofiler_service_callback_tracing_kind_t
 * the operation kind can be determined from the following:
- *  ::rocprofiler_marker_trace_record_operation_t for Markers
- *  ::rocprofiler_hsa_trace_record_operation_t for HSA API
- *  ::rocprofiler_hip_trace_record_operation_t for HIP API
- *  ::rocprofiler_code_object_record_operation_t for Code object tracing
+ *  rocprofiler_marker_trace_record_operation_t for Markers
+ *  rocprofiler_hsa_trace_record_operation_t for HSA API
+ *  rocprofiler_hip_trace_record_operation_t for HIP API
+ *  rocprofiler_code_object_record_operation_t for Code object tracing
 *
 */
 typedef uint32_t rocprofiler_tracer_callback_operation_t;
@@ -566,7 +566,7 @@ typedef uint32_t rocprofiler_trace_record_operation_kind_t;
 * @brief Query callback kind operation name.
 *
 * @param [in] kind
- * @param [in] api_trace_operation_id
+ * @param [in] api_trace_operation
 * @param [out] name if nullptr, size will be returned
 * @param [out] size
 * @return ::rocprofiler_status_t
@@ -971,24 +971,16 @@ typedef struct
 * @param [out] queue_id
 * @param [out] agent_id
 * @param [out] correlation_id
- * @param [out] dispatch_packet
+ * @param [out] dispatch_packet It can be used to get the kernel descriptor and then using
+ * code_object tracing, we can get the kernel name. `dispatch_packet->reserved2` is the
+ * correlation_id used to correlate the dispatch packet with the corresponding API call.
 * @param [out] callback_data_args
 * @param [in] config
 */
 typedef void (*rocprofiler_profile_counting_dispatch_callback_t)(
-    rocprofiler_queue_id_t       queue_id,
-    rocprofiler_agent_t          agent_id,
-    rocprofiler_correlation_id_t correlation_id,
-    /**
-     * @brief Kernel Dispatch Packet
-     *
-     * It can be used to get the kernel descriptor and then using code_object
-     * tracing, we can get the kernel name.
-     *
-     * dispatch_packet->reserved2 is the correlation_id used to correlate the
-     * dispatch packet with the corresponding API call.
-     *
-     */
+    rocprofiler_queue_id_t              queue_id,
+    rocprofiler_agent_t                 agent_id,
+    rocprofiler_correlation_id_t        correlation_id,
    const hsa_kernel_dispatch_packet_t* dispatch_packet,
    void*                               callback_data_args,
    rocprofiler_profile_config_id_t*    config);
@@ -997,6 +989,7 @@ typedef void (*rocprofiler_profile_counting_dispatch_callback_t)(
 * @brief Configure Dispatch Profile Counting Service.
 *
 * @param [in] context_id
+ * @param [in] agent_id
 * @param [in] buffer_id
 * @param [in] callback
 * @param [in] callback_data_args
@@ -1144,7 +1137,7 @@ typedef enum
 * @brief Create PC Sampling Service.
 *
 * @param [in] context_id
- * @param [in] agent_id
+ * @param [in] agent
 * @param [in] method
 * @param [in] unit
 * @param [in] interval
@@ -1172,7 +1165,7 @@ struct rocprofiler_pc_sampling_configuration_s
 /**
 * @brief Query PC Sampling Configuration.
 *
- * @param [in] agent_id
+ * @param [in] agent
 * @param [out] config
 * @param [out] config_count
 * @return ::rocprofiler_status_t
@@ -1291,6 +1284,7 @@ typedef enum
 * to 0 then the callback will be called on every record
 * @param [in] policy Behavior policy when buffer is full
 * @param [in] callback Callback to invoke when buffer is flushed/full
+ * @param [in] callback_data Data to provide in callback function
 * @param [out] buffer_id Identification handle for buffer
 * @return ::rocprofiler_status_t
 */
@@ -90,7 +90,7 @@ rocprofiler_plugin_initialize(uint32_t rocprofiler_major_version,
 * Finalize plugin.
 * This must be called after ::rocprofiler_plugin_initialize and after all
 * profiling data has been reported by
- * ::rocprofiler_plugin_write_kernel_records
+ * rocprofiler_plugin_write_kernel_records
 */
 ROCPROFILER_EXPORT void
 rocprofiler_plugin_finalize();
@@ -108,10 +108,10 @@ rocprofiler_plugin_finalize();
 /**
 * Report Buffer Records.
 *
- * @param[in] begin Pointer to the first record.
- * @param[in] end Pointer to one past the last record.
 * @param[in] context_id context ID
 * @param[in] buffer_id Buffer ID
+ * @param[in] headers Array of ::rocprofiler_record_header_t
+ * @param[in] num_headers Number of ::rocprofiler_record_header_t entries in array
 * @return Returns 0 on success and -1 on error.
 */
 ROCPROFILER_EXPORT int
@@ -124,8 +124,6 @@ rocprofiler_plugin_write_buffer_records(rocprofiler_context_id_t      context_id
 * Report Synchronous Record.
 *
 * @param[in] record Synchronous Tracer record.
- * @param[in] data : api_data
- * @param[in] tracer_data :Tracer record extra data such as function name and kernel name
 * @return Returns 0 on success and -1 on error.
 */

@@ -0,0 +1,39 @@
+#!/bin/bash -e
+
+message()
+{
+    echo -e "\n\n##### ${@}... #####\n"
+}
+
+WORK_DIR=$(cd $(dirname ${BASH_SOURCE[0]})/../docs &> /dev/null && pwd)
+SOURCE_DIR=$(cd ${WORK_DIR}/../.. &> /dev/null && pwd)
+
+message "Working directory is ${WORK_DIR}"
+message "Source directory is ${SOURCE_DIR}"
+
+message "Changing directory to ${WORK_DIR}"
+cd ${WORK_DIR}
+
+message "Generating rocprofiler.dox"
+cmake -DSOURCE_DIR=${SOURCE_DIR} -P ${WORK_DIR}/generate-doxyfile.cmake
+
+message "Generating doxygen xml files"
+doxygen rocprofiler.dox
+doxygen rocprofiler.dox
+
+message "Running doxysphinx"
+doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html
+
+message "Building html documentation"
+make html SPHINXOPTS="-W --keep-going -n"
+
+if [ -d ${SOURCE_DIR}/docs ]; then
+    message "Removing stale documentation in ${SOURCE_DIR}/docs/"
+    rm -rf ${SOURCE_DIR}/docs/*
+
+    message "Adding nojekyll to docs/"
+    cp -r ${WORK_DIR}/.nojekyll ${SOURCE_DIR}/docs/.nojekyll
+
+    message "Copying source/docs/_build/html/* to docs/"
+    cp -r ${WORK_DIR}/_build/html/* ${SOURCE_DIR}/docs/
+fi
@@ -0,0 +1,10 @@
+#!/bin/bash -e
+
+WORK_DIR=$(cd $(dirname ${BASH_SOURCE[0]})/../docs &> /dev/null && pwd)
+SOURCE_DIR=$(cd ${WORK_DIR}/../.. &> /dev/null && pwd)
+
+cmake -DSOURCE_DIR=${SOURCE_DIR} -P generate-doxyfile.cmake
+
+doxygen rocprofiler.dox
+
+doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html