Skip to content

Commit 7f9b67e

Browse files
eparshuteparshut
authored
Add ITT/JIT API documentation source files and gh-action to deploy docs to gh-pages (#175)
* doc: add docs source files and gh-action to deploy docs to gh-pages * doc: huge refactoring * doc: address review comments * doc: code cleanup * ci: update deploy-docs workflow * doc: update reference collector readme * doc: update readme
1 parent e535d56 commit 7f9b67e

41 files changed

Lines changed: 3759 additions & 32 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
paths:
8+
- 'docs/**' # Trigger only when the source docs files are modified
9+
10+
permissions:
11+
contents: write
12+
13+
jobs:
14+
build_and_deploy:
15+
name: Build and deploy documentation
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
20+
- name: Install dependencies
21+
run: |
22+
python -m pip install --upgrade pip
23+
pip install sphinx sphinx_rtd_theme
24+
- name: Build documentation
25+
run: python -m sphinx docs build
26+
- name: Deploy to GitHub Pages
27+
uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.2
28+
with:
29+
github_token: ${{ secrets.GITHUB_TOKEN }}
30+
publish_branch: gh-pages
31+
publish_dir: build
32+
force_orphan: true

‎README.md‎

Lines changed: 37 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API
2-
==================================================================================
1+
Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
2+
===============================================================================
33

44
[![Build Status](https://github.com/intel/ittapi/actions/workflows/main.yml/badge.svg?branch=master&event=push)](https://github.com/intel/ittapi/actions)
55
[![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
88
[![Package on crates.io](https://img.shields.io/crates/v/ittapi.svg)](https://crates.io/crates/ittapi)
99
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/intel/ittapi/badge)](https://securityscorecards.dev/viewer/?uri=github.com/intel/ittapi)
1010

11-
This ITT/JIT open source profiling API includes:
11+
This repository contains the following profiling APIs:
1212

13-
- Instrumentation and Tracing Technology (ITT) API
14-
- Just-In-Time (JIT) Profiling API
13+
- **Instrumentation and Tracing Technology (ITT) API**
14+
Powers your application to generate and control the collection of trace data
15+
during its execution, seamlessly integrating with Intel tools.
16+
- **Just-In-Time (JIT) Profiling API**
17+
Reports detailed information about just-in-time (JIT) compiled code, enabling
18+
you to profile the performance of dynamically generated code.
1519

16-
The Instrumentation and Tracing Technology (ITT) API enables your application
17-
to generate and control the collection of trace data during its execution
18-
across different Intel tools.
20+
The ITT/JIT APIs consist of two parts:
1921

20-
ITT API consists of two parts: a _static part_ and a _dynamic part_. The
21-
_dynamic part_ is specific for a tool and distributed only with a particular
22-
tool. The _static part_ is a common part shared between tools. Currently, the
23-
static part of ITT API is distributed as a static library and released under
24-
a BSD/GPLv2 dual license with every tool supporting ITT API.
22+
- **Static Part**
23+
An open-source static library that you compile and link with your application.
24+
- **Dynamic Part**
25+
A tool-specific shared library that collects and writes trace data. You can
26+
find the reference implementation of the dynamic part as a *Reference Collector*
27+
[here](./src/ittnotify_refcol/README.md).
2528

2629
### Build
2730

2831
To build the library:
29-
- On Windows, Linux, FreeBSD and OSX: requires [cmake](https://cmake.org) to be set in `PATH`
30-
- Windows: requires Visual Studio installed or requires [Ninja](https://github.com/ninja-build/ninja/releases) to be set in `PATH`
31-
- 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
32-
- To list available build options execute: `python buildall.py -h`
32+
33+
- Get general development tools, including C/C++ Compiler
34+
- Install [Python](https://python.org) 3.6 or later
35+
- Install [CMake](https://cmake.org) 3.5 or later
36+
- For a Windows* system, install one of these:
37+
- [Microsoft Visual Studio](https://visualstudio.microsoft.com) 2015 or later
38+
- [Ninja](https://github.com/ninja-build/ninja/releases) 1.9 or later
39+
- To enable support for Fortran, install the
40+
[Intel Fortran Compiler](https://www.intel.com/content/www/us/en/docs/fortran-compiler/get-started-guide/current/overview.html)
41+
- To list available build options execute: `python buildall.py -h`
42+
3343
```
3444
usage: buildall.py [-h] [-d] [-c] [-v] [-pt] [-ft] [--force_bits]
3545
@@ -44,15 +54,21 @@ optional arguments:
4454
--vs specify visual studio version (Windows only)
4555
--cmake_gen specify cmake build generator (Windows only)
4656
```
57+
58+
### Documentation
59+
60+
Find complete documentation for ITT/JIT APIs on the
61+
[ITT/JIT APIs Documentation Page](https://intel.github.io/ittapi)
62+
4763
### License
4864

4965
All code in the repo is dual licensed under GPLv2 and 3-Clause BSD licenses
5066

51-
### Contributing
67+
### Make Contributions
5268

53-
To contribute, please see our [contributing guide](CONTRIBUTING.md)
54-
To report bugs or request enhancements, please use the "Issues" page on GitHub
69+
Learn how to contribute using our [contribution guide](CONTRIBUTING.md)
70+
To report bugs or request enhancements, please use the [Issues page on GitHub](https://github.com/intel/ittapi/issues)
5571

5672
### Security
5773

58-
Please refer to the [security policy](SECURITY.md) for reporting vulnerabilties.
74+
To report vulnerabilities, refer to our [security policy](SECURITY.md)

‎docs/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# ITT/JIT APIs Documentation
2+
3+
## Overview
4+
5+
This repository contains the source files for the ITT/JIT APIs online documentation,
6+
which is hosted on GitHub Pages. [View the documentation here](link).
7+
8+
## Build Documentation from Sources
9+
10+
1. Install Sphinx and the required Sphinx theme:
11+
```bash
12+
pip install sphinx sphinx_rtd_theme
13+
2. Navigate to the Documentation source folder:
14+
```bash
15+
cd <ittapi_dir>/docs
16+
3. Build the Documentation with the following command:
17+
```bash
18+
python -m sphinx . build

‎docs/conf.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#
2+
# Copyright (C) 2025 Intel Corporation
3+
#
4+
# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
5+
#
6+
7+
# Configuration file for the Sphinx documentation builder.
8+
#
9+
# For the full list of built-in configuration values, see the documentation:
10+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
11+
12+
# -- Project information -----------------------------------------------------
13+
14+
project = 'ITT/JIT APIs Documentation'
15+
copyright = '2025 Intel Corporation'
16+
author = 'Intel Corporation'
17+
18+
# -- General configuration ---------------------------------------------------
19+
20+
extensions = [
21+
'sphinx_rtd_theme', # ReadTheDocs theme
22+
'sphinx.ext.githubpages', # Support for GitHub Pages
23+
'sphinx.ext.ifconfig', # Conditional inclusion of content
24+
]
25+
26+
templates_path = ['_templates']
27+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
28+
29+
# -- Options for HTML output -------------------------------------------------
30+
31+
import sphinx_rtd_theme
32+
33+
html_theme = 'sphinx_rtd_theme'
34+
html_theme_options = {
35+
'style_external_links': True,
36+
}
37+
38+
html_baseurl = 'https://intel.github.io/ittapi/'

‎docs/index.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. _index:
2+
3+
The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
4+
===================================================================================
5+
6+
7+
The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
8+
are open source profiling APIs that you use with Intel software tools, to collect
9+
and manage trace data during performance analysis. You can profile with ITT/JIT APIs
10+
when you use Intel® VTune Profiler and Intel® Graphics Performance Analyzers (Intel® GPA).
11+
12+
This repository contains documentation that explains the use of these APIs.
13+
14+
15+
.. toctree::
16+
:maxdepth: 1
17+
:caption: Contents:
18+
19+
src/overview
20+
src/build
21+
src/api-support
22+
src/ref_collector
23+
GitHub Project <https://github.com/intel/ittapi>
24+

‎docs/requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx
2+
sphinx_rtd_theme

‎docs/src/api-support.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. _api-support:
2+
3+
Use the ITT/JIT APIs
4+
====================
5+
6+
7+
This section describes how you use ITT/JIT APIs with various environments.
8+
The ITT/JIT APIs are a set of C/C++ functions and use no Java* or .NET* code.
9+
For support with your runtime environment, use a Java Native Interface (JNI)
10+
or C/C++ function call from the managed code.
11+
12+
13+
C/C++ API Usage and Reference:
14+
------------------------------
15+
16+
.. toctree::
17+
:maxdepth: 1
18+
19+
20+
itt-api-support
21+
jit-api-support
22+
23+
24+
Other Language API Bindings:
25+
----------------------------
26+
27+
.. toctree::
28+
:maxdepth: 1
29+
30+
31+
Rust ITT API Bindings <https://docs.rs/ittapi/latest/ittapi>
32+
Python ITT API Bindings <https://pypi.org/project/ittapi>
33+

‎docs/src/build.rst‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _build:
2+
3+
Build from Source Code
4+
======================
5+
6+
Technical Requirements
7+
----------------------
8+
9+
Before you build the ITT/JIT APIs, make sure you have the following hardware and software tools:
10+
11+
- Get general development tools, including C/C++ Compiler
12+
- Install `Python <https://python.org>`__ 3.6 or later
13+
- Install `CMake <https://cmake.org>`__ 3.5 or later
14+
- For a Windows* system, install one of these:
15+
16+
- `Microsoft Visual Studio <https://visualstudio.microsoft.com>`__ 2015 or later
17+
- `Ninja <https://ninja-build.org>`__ 1.9 or later
18+
19+
- To enable support for Fortran, install the `Intel Fortran Compiler
20+
<https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler-download.html>`__
21+
22+
23+
Get the ITT/JIT APIs Source Code
24+
--------------------------------
25+
26+
To get the source code for the ITT/JIT APIs, do one of the following:
27+
28+
- Download it from `the latest public Release <https://github.com/intel/ittapi/releases>`__
29+
- Clone the repository:
30+
31+
.. code-block:: console
32+
33+
git clone https://github.com/intel/ittapi.git
34+
35+
36+
Build the ITT/JIT APIs
37+
----------------------
38+
39+
To build the ITT/JIT APIs static library, run this command:
40+
41+
.. code-block:: console
42+
43+
python buildall.py <options>
44+
45+
46+
Use these options to configure the build process:
47+
48+
.. code-block:: console
49+
50+
usage: python buildall.py [-h] [-d] [-c] [-v] [-pt] [-ft] [--force_bits]
51+
52+
optional arguments:
53+
-h, --help show this help message and exit
54+
-d, --debug specify debug build configuration (release by default)
55+
-c, --clean delete any intermediate and output files
56+
-v, --verbose enable verbose output from build process
57+
-pt, --ptmark enable anomaly detection support
58+
-ft, --fortran enable fortran support
59+
--force_bits specify bit version for the target
60+
--vs specify visual studio version (Windows only)
61+
--cmake_gen specify cmake build generator (Windows only)

0 commit comments

Comments
 (0)