ifdef::env-github[] :note-caption: :information_source: endif::[]

= ANARI(R)^ API Documentation Project

This repository contains sources for the formal documentation of the ANARI API. This includes:

[options="compact"]

• The ANARI API Specification
• Specification of ANARI extensions

The authoritative public repository is located at https://github.com/KhronosGroup/ANARI-Docs/. It hosts a public Issue tracker, and outside developers can file proposed patches (Pull Requests) against the Specification, subject to approval by Khronos.

The generated ANARI specification can be found in the repository located at https://github.com/KhronosGroup/ANARI-Registry.

== Branch Structure

The current Specification is maintained in the main branch of the repository. From this branch it is possible to generate Specifications for any published version of ANARI (currently 1.0), and incorporating any desired set of extensions.

== Directory Structure

The directory structure is as follows:

README.adoc           This file
BUILD.adoc            Documents how to build the specifications, and man pages
COPYING.md            Copyright and licensing information
CODE_OF_CONDUCT.md    Code of Conduct
ChangeLog.txt         Change log summary for each public spec update
Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
appendices/           Specification appendices
chapters/             Specification chapters
config/               Asciidoctor configuration, CSS, and index generator
images/               Images (figures, diagrams, icons)
man/                  Reference (man) pages for the API; mostly extracted from the spec source
out/                  Default directory for the generated documents
scripts/              Helper scripts used in specification, header, and reference page generation
style/                Sources for "styleguide" (ANARI Documentation and Extensions: Procedures and Conventions)

== Building the Specification and Reference Pages

The document sources are marked up in Asciidoctor format, and we use asciidoctor and related toolchain components to generate output documents. See link:BUILD.adoc[BUILD.adoc] for more information on installing the toolchain and building the Specification.

== Generating Headers and Related Files

See link:xml/README.adoc[xml/README.adoc].

The header files (include/anari/anari*.h) and many parts of the specification and reference page documents are generated from descriptions in the XML API Registry (xml/an.xml). The generated files are not checked into the repository. If you change an.xml, you can regenerate the headers by going into xml/ and running:

$ make clean install

The other generated files are built as required via dependencies in the top-level Makefile.