From 729c34fb60f2ca7c706a0748dbd64782a84697e9 Mon Sep 17 00:00:00 2001 From: "Jonathan R. Madsen" Date: Tue, 12 Sep 2023 12:34:36 -0500 Subject: [PATCH] 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 --- .github/workflows/docs.yml | 74 +++++ .gitmodules | 3 + external/doxygen-awesome-css | 1 + source/docs/.gitignore | 5 + source/docs/.nojekyll | 0 source/docs/Makefile | 20 ++ source/docs/README.md | 19 ++ source/docs/about.md | 11 + source/docs/conf.py | 163 +++++++++ source/docs/developer_api.md | 12 + source/docs/environment.yml | 142 ++++++++ source/docs/features.md | 11 + source/docs/generate-doxyfile.cmake | 19 ++ source/docs/index.md | 13 + source/docs/installation.md | 50 +++ source/docs/rocprofiler.dox.in | 309 ++++++++++++++++++ source/include/rocprofiler/rocprofiler.h | 54 ++- .../include/rocprofiler/rocprofiler_plugin.h | 8 +- source/scripts/update-docs.sh | 39 +++ source/scripts/update-doxygen.sh | 10 + 20 files changed, 928 insertions(+), 35 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 160000 external/doxygen-awesome-css create mode 100644 source/docs/.gitignore create mode 100644 source/docs/.nojekyll create mode 100644 source/docs/Makefile create mode 100644 source/docs/README.md create mode 100644 source/docs/about.md create mode 100644 source/docs/conf.py create mode 100644 source/docs/developer_api.md create mode 100644 source/docs/environment.yml create mode 100644 source/docs/features.md create mode 100644 source/docs/generate-doxyfile.cmake create mode 100644 source/docs/index.md create mode 100644 source/docs/installation.md create mode 100644 source/docs/rocprofiler.dox.in create mode 100755 source/scripts/update-docs.sh create mode 100755 source/scripts/update-doxygen.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..38c4973abc --- /dev/null +++ b/.github/workflows/docs.yml @@ -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 diff --git a/.gitmodules b/.gitmodules index 11275350a8..edf419b3a4 100644 --- a/.gitmodules +++ b/.gitmodules @@ -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 diff --git a/external/doxygen-awesome-css b/external/doxygen-awesome-css new file mode 160000 index 0000000000..df83fbf22c --- /dev/null +++ b/external/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit df83fbf22cfff76b875c13d324baf584c74e96d0 diff --git a/source/docs/.gitignore b/source/docs/.gitignore new file mode 100644 index 0000000000..efffe944ee --- /dev/null +++ b/source/docs/.gitignore @@ -0,0 +1,5 @@ +/build* +/_build +/_doxygen +/.gitinfo +/rocprofiler.dox diff --git a/source/docs/.nojekyll b/source/docs/.nojekyll new file mode 100644 index 0000000000..e69de29bb2 diff --git a/source/docs/Makefile b/source/docs/Makefile new file mode 100644 index 0000000000..d4bb2cbb9e --- /dev/null +++ b/source/docs/Makefile @@ -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) diff --git a/source/docs/README.md b/source/docs/README.md new file mode 100644 index 0000000000..5f7d274f70 --- /dev/null +++ b/source/docs/README.md @@ -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. diff --git a/source/docs/about.md b/source/docs/about.md new file mode 100644 index 0000000000..6e617a783b --- /dev/null +++ b/source/docs/about.md @@ -0,0 +1,11 @@ +# About + +```eval_rst +.. toctree:: + :glob: + :maxdepth: 4 +``` + +## Overview + +TODO: Overview of rocprofiler v2 diff --git a/source/docs/conf.py b/source/docs/conf.py new file mode 100644 index 0000000000..dbf0153479 --- /dev/null +++ b/source/docs/conf.py @@ -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 (-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) diff --git a/source/docs/developer_api.md b/source/docs/developer_api.md new file mode 100644 index 0000000000..22d81369eb --- /dev/null +++ b/source/docs/developer_api.md @@ -0,0 +1,12 @@ +# Developer API + +```eval_rst +.. toctree:: + :glob: + :maxdepth: 4 + + _doxygen/html/topics + _doxygen/html/files + _doxygen/html/annotated + _doxygen/html/classes +``` diff --git a/source/docs/environment.yml b/source/docs/environment.yml new file mode 100644 index 0000000000..7668b49c1f --- /dev/null +++ b/source/docs/environment.yml @@ -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 diff --git a/source/docs/features.md b/source/docs/features.md new file mode 100644 index 0000000000..91547d5269 --- /dev/null +++ b/source/docs/features.md @@ -0,0 +1,11 @@ +# Features + +```eval_rst +.. toctree:: + :glob: + :maxdepth: 4 +``` + +## Overview + +TODO: Overview of rocprofiler v2 features diff --git a/source/docs/generate-doxyfile.cmake b/source/docs/generate-doxyfile.cmake new file mode 100644 index 0000000000..63758adfed --- /dev/null +++ b/source/docs/generate-doxyfile.cmake @@ -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) diff --git a/source/docs/index.md b/source/docs/index.md new file mode 100644 index 0000000000..0961e13205 --- /dev/null +++ b/source/docs/index.md @@ -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 +``` diff --git a/source/docs/installation.md b/source/docs/installation.md new file mode 100644 index 0000000000..7dd51d2796 --- /dev/null +++ b/source/docs/installation.md @@ -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` diff --git a/source/docs/rocprofiler.dox.in b/source/docs/rocprofiler.dox.in new file mode 100644 index 0000000000..2d5c3c2b59 --- /dev/null +++ b/source/docs/rocprofiler.dox.in @@ -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 = diff --git a/source/include/rocprofiler/rocprofiler.h b/source/include/rocprofiler/rocprofiler.h index 834f8e965f..4254e0a286 100644 --- a/source/include/rocprofiler/rocprofiler.h +++ b/source/include/rocprofiler/rocprofiler.h @@ -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 */ diff --git a/source/include/rocprofiler/rocprofiler_plugin.h b/source/include/rocprofiler/rocprofiler_plugin.h index afe8b8d6d1..9fa8d34ce7 100644 --- a/source/include/rocprofiler/rocprofiler_plugin.h +++ b/source/include/rocprofiler/rocprofiler_plugin.h @@ -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. */ diff --git a/source/scripts/update-docs.sh b/source/scripts/update-docs.sh new file mode 100755 index 0000000000..c2d817adfc --- /dev/null +++ b/source/scripts/update-docs.sh @@ -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 diff --git a/source/scripts/update-doxygen.sh b/source/scripts/update-doxygen.sh new file mode 100755 index 0000000000..e183d771e2 --- /dev/null +++ b/source/scripts/update-doxygen.sh @@ -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