Add ITT/JIT API documentation source files and gh-action to deploy docs to gh-pages

.github/workflows/deploy-docs.yml

@@ -0,0 +1,32 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**' # Trigger only when the source docs files are modified
+
+permissions:
+  contents: write
+
+jobs:
+  build_and_deploy:
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx_rtd_theme
+      - name: Build documentation
+        run: python -m sphinx docs build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: build
+          force_orphan: true

README.md

@@ -1,5 +1,5 @@
-Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API
-==================================================================================
+Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
+===============================================================================
 
 [![Build Status](https://github.com/intel/ittapi/actions/workflows/main.yml/badge.svg?branch=master&event=push)](https://github.com/intel/ittapi/actions)
 [![CodeQL](https://github.com/intel/ittapi/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/intel/ittapi/security/code-scanning/tools/CodeQL/status)
@@ -8,28 +8,38 @@ Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API
 [![Package on crates.io](https://img.shields.io/crates/v/ittapi.svg)](https://crates.io/crates/ittapi)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/intel/ittapi/badge)](https://securityscorecards.dev/viewer/?uri=github.com/intel/ittapi)
 
-This ITT/JIT open source profiling API includes:
+This repository contains the following profiling APIs:
 
-  - Instrumentation and Tracing Technology (ITT) API
-  - Just-In-Time (JIT) Profiling API
+- **Instrumentation and Tracing Technology (ITT) API**  
+  Powers your application to generate and control the collection of trace data
+  during its execution, seamlessly integrating with Intel tools.
+- **Just-In-Time (JIT) Profiling API**  
+  Reports detailed information about just-in-time (JIT) compiled code, enabling
+  you to profile the performance of dynamically generated code.
 
-The Instrumentation and Tracing Technology (ITT) API enables your application
-to generate and control the collection of trace data during its execution 
-across different Intel tools.
+The ITT/JIT APIs consist of two parts:
 
-ITT API consists of two parts: a _static part_ and a _dynamic part_. The
-_dynamic part_ is specific for a tool and distributed only with a particular
-tool. The _static part_ is a common part shared between tools. Currently, the
-static part of ITT API is distributed as a static library and released under
-a BSD/GPLv2 dual license with every tool supporting ITT API.
+- **Static Part**  
+  An open-source static library that you compile and link with your application.
+- **Dynamic Part**  
+  A tool-specific shared library that collects and writes trace data. You can
+  find the reference implementation of the dynamic part as a *Reference Collector*
+  [here](./src/ittnotify_refcol/README.md).
 
 ### Build
 
 To build the library:
- - On Windows, Linux, FreeBSD and OSX: requires [cmake](https://cmake.org) to be set in `PATH`
- - Windows: requires Visual Studio installed or requires [Ninja](https://github.com/ninja-build/ninja/releases) to be set in `PATH`
- - To enable fortran support requires [Intel Fortran Compiler](https://www.intel.com/content/www/us/en/docs/fortran-compiler/get-started-guide/current/overview.html) installed
- - To list available build options execute: `python buildall.py -h`
+
+- Get general development tools, including C/C++ Compiler
+- Install [Python](https://python.org) 3.6 or later
+- Install [CMake](https://cmake.org) 3.5 or later
+- For a Windows* system, install one of these:
+  - [Microsoft Visual Studio](https://visualstudio.microsoft.com) 2015 or later
+  - [Ninja](https://github.com/ninja-build/ninja/releases) 1.9 or later
+-  To enable support for Fortran, install the
+  [Intel Fortran Compiler](https://www.intel.com/content/www/us/en/docs/fortran-compiler/get-started-guide/current/overview.html)
+- To list available build options execute: `python buildall.py -h`
+
 ```
 usage: buildall.py [-h] [-d] [-c] [-v] [-pt] [-ft] [--force_bits]
 
@@ -44,15 +54,21 @@ optional arguments:
   --vs            specify visual studio version (Windows only)
   --cmake_gen     specify cmake build generator (Windows only)
 ```
+
+### Documentation
+
+Find complete documentation for ITT/JIT APIs on the
+[ITT/JIT APIs Documentation Page](https://intel.github.io/ittapi)
+
 ### License
 
 All code in the repo is dual licensed under GPLv2 and 3-Clause BSD licenses
 
-### Contributing
+### Make Contributions
 
-To contribute, please see our [contributing guide](CONTRIBUTING.md)  
-To report bugs or request enhancements, please use the "Issues" page on GitHub
+Learn how to contribute using our [contribution guide](CONTRIBUTING.md)  
+To report bugs or request enhancements, please use the [Issues page on GitHub](https://github.com/intel/ittapi/issues)
 
 ### Security
 
-Please refer to the [security policy](SECURITY.md) for reporting vulnerabilties.
+To report vulnerabilities, refer to our [security policy](SECURITY.md)

docs/README.md

@@ -0,0 +1,18 @@
+# ITT/JIT APIs Documentation
+
+## Overview
+
+This repository contains the source files for the ITT/JIT APIs online documentation,
+which is hosted on GitHub Pages. [View the documentation here](link).
+
+## Build Documentation from Sources
+
+1. Install Sphinx and the required Sphinx theme:  
+   ```bash
+   pip install sphinx sphinx_rtd_theme
+2. Navigate to the Documentation source folder:  
+   ```bash
+   cd <ittapi_dir>/docs
+3. Build the Documentation with the following command:  
+    ```bash
+    python -m sphinx . build

docs/conf.py

@@ -0,0 +1,38 @@
+#
+# Copyright (C) 2025 Intel Corporation
+#
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
+#
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+
+project = 'ITT/JIT APIs Documentation'
+copyright = '2025 Intel Corporation'
+author = 'Intel Corporation'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx_rtd_theme',        # ReadTheDocs theme
+    'sphinx.ext.githubpages',  # Support for GitHub Pages
+    'sphinx.ext.ifconfig',     # Conditional inclusion of content
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+import sphinx_rtd_theme
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'style_external_links': True,
+}
+
+html_baseurl = 'https://intel.github.io/ittapi/'

docs/index.rst

@@ -0,0 +1,24 @@
+.. _index:
+
+The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
+===================================================================================
+
+
+The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
+are open source profiling APIs that you use with Intel software tools, to collect
+and manage trace data during performance analysis. You can profile with ITT/JIT APIs
+when you use Intel® VTune Profiler and Intel® Graphics Performance Analyzers (Intel® GPA).
+
+This repository contains documentation that explains the use of these APIs.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   src/overview
+   src/build
+   src/api-support
+   src/ref_collector
+   GitHub Project <https://github.com/intel/ittapi>
+

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/src/api-support.rst

@@ -0,0 +1,33 @@
+.. _api-support:
+
+Use the ITT/JIT APIs
+====================
+
+
+This section describes how you use ITT/JIT APIs with various environments.
+The ITT/JIT APIs are a set of C/C++ functions and use no Java* or .NET* code.
+For support with your runtime environment, use a Java Native Interface (JNI)
+or C/C++ function call from the managed code.
+
+
+C/C++ API Usage and Reference:
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+
+   itt-api-support
+   jit-api-support
+
+
+Other Language API Bindings:
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+
+   Rust ITT API Bindings <https://docs.rs/ittapi/latest/ittapi>
+   Python ITT API Bindings <https://pypi.org/project/ittapi>
+

docs/src/build.rst

@@ -0,0 +1,61 @@
+.. _build:
+
+Build from Source Code
+======================
+
+Technical Requirements
+----------------------
+
+Before you build the ITT/JIT APIs, make sure you have the following hardware and software tools:
+
+-  Get general development tools, including C/C++ Compiler
+-  Install `Python <https://python.org>`__  3.6 or later
+-  Install `CMake <https://cmake.org>`__ 3.5 or later
+-  For a Windows* system, install one of these:
+
+   -  `Microsoft Visual Studio <https://visualstudio.microsoft.com>`__ 2015 or later
+   -  `Ninja <https://ninja-build.org>`__ 1.9 or later
+
+-  To enable support for Fortran, install the `Intel Fortran Compiler
+   <https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler-download.html>`__
+
+
+Get the ITT/JIT APIs Source Code
+--------------------------------
+
+To get the source code for the ITT/JIT APIs, do one of the following:
+
+-  Download it from `the latest public Release <https://github.com/intel/ittapi/releases>`__
+-  Clone the repository:
+
+.. code-block:: console
+
+	git clone https://github.com/intel/ittapi.git
+
+
+Build the ITT/JIT APIs
+----------------------
+
+To build the ITT/JIT APIs static library, run this command:
+
+.. code-block:: console
+
+	python buildall.py <options>
+
+
+Use these options to configure the build process:
+
+.. code-block:: console
+
+    usage: python buildall.py [-h] [-d] [-c] [-v] [-pt] [-ft] [--force_bits]
+
+    optional arguments:
+      -h, --help      show this help message and exit
+      -d, --debug     specify debug build configuration (release by default)
+      -c, --clean     delete any intermediate and output files
+      -v, --verbose   enable verbose output from build process
+      -pt, --ptmark   enable anomaly detection support
+      -ft, --fortran  enable fortran support
+      --force_bits    specify bit version for the target
+      --vs            specify visual studio version (Windows only)
+      --cmake_gen     specify cmake build generator (Windows only)