.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0

===================== oneAPI Specifications

.. image:: https://github.com/uxlfoundation/oneAPI-spec/actions/workflows/pr.yml/badge.svg :target: https://github.com/uxlfoundation/oneAPI-spec/actions/workflows/pr.yml

.. image:: https://api.reuse.software/badge/github.com/uxlfoundation/oneAPI-spec :target: https://api.reuse.software/info/github.com/uxlfoundation/oneAPI-spec :alt: REUSE status

.. image:: https://www.bestpractices.dev/projects/8323/badge :target: https://www.bestpractices.dev/projects/8323

This repository contains the sources for the oneAPI Specification. For the latest build from main branch, see HTML and PDF_.

For more information about oneAPI, see oneapi.io. For information about future releases of the oneAPI specification, see the roadmap. To be notified about new releases, become a release-only watcher of this repo.

The document is written using reStructuredText_ and built with Sphinx_ using a theme provided by Read the Docs_.

.. contents:: :local: :depth: 1

License

The oneAPI specification is licensed under the Creative Commons Attribution 4.0 International License.

See LICENSE <LICENSE.rst>__ for more information.

Contribute

See CONTRIBUTING <CONTRIBUTING.rst>__ for more information.

.. _build_spec:

Build the Specification

To build the specification document locally, clone this repository to your local system and follow the setup and build instructions. The setup and build steps make use of scripts/oneapi.py, a helper script for maintenance tasks. You can also look at the source if you want to see how to do the same task manually.

Setup

Install Python 3, Doxygen (>= 1.8.17), LaTeX, etc. To install on Ubuntu::

sudo scripts/install.sh

Create and activate a Python virtual environment with all required tools::

python scripts/oneapi.py spec-venv source spec-venv/bin/activate

To install directly with pip::

pip install -r requirements.txt

To install on Windows::

python scripts\oneapi.py spec-venv spec-venv\Scripts\activate

Build the Docs

To build the HTML document, use the following command::

python scripts/oneapi.py html

The document is organized as a book with chapters. Each element of oneAPI is its own chapter and can be built separately. For example, to build the oneVPL chapter, use the following command::

python scripts/oneapi.py html source/elements/oneVPL

To view the HTML docs, visit build/html/index.html in your browser using a file:// URL.

Build the pdf version wit the following command::

python scripts/oneapi.py latexpdf

The generated PDF will be located at build/latexpdf/oneAPI-spec.pdf.

Spell check::

python oneapi.doc. --verbose spelling

-- CI

We use GitHub actions. See <.github/workflows/ci.yml>_.

PR's trigger the CI to build the document and save it as an artifact. If you are working in a fork on GitHub, commits to the main branch will build and publish the document in the GitHub pages associated with the repository.

Adding licenses to files

Use the reuse_ tool

Code examples::

reuse addheader --copyright "Constributors to the oneapi-spec project" --license MIT source/examples/host-task.cpp

Doc sources::

reuse addheader --copyright "Constributors to the oneapi-spec project" --license CC-BY-4.0 source/index.rst

Making a Release

1. Update:

   • oneapi-doc.json
   • releases/index.rst

2. Tag it.

3. Publish with oneAPI doc repo

.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _Sphinx: http://www.sphinx-doc.org/en/master/ .. _Read the Docs: https://readthedocs.org/ .. _oneAPI Specification: https://oneapi.io/spec .. _reuse: https://pypi.org/project/reuse/ .. _HTML: https://uxlfoundation.github.io/oneAPI-spec/spec/ .. _PDF: https://uxlfoundation.github.io/oneAPI-spec/spec/oneAPI-spec.pdf .. _oneapi.io: https://oneapi.io .. _roadmap: roadmap.rst