Inventory File Formats

An Inventory object can be be written to disk using the DocInventories.save function in the formats detailed below.

See also DocInventories.MIME_TYPES for file extensions and corresponding MIME types.

Sphinx Inventory Format

The Sphinx inventory format is the format of the objects.inv file that is automatically created for every documentation generated via Sphinx, and, as of Documenter>=1.3.0, for every documentation generated via Documenter.

It is documented extensively as part of the sphobjinv project. In short, the objects.inv file starts with a four-line plain text header of the form

# Sphinx inventory version 2
# Project: <project>
# Version: <version>
# The remainder of this file is compressed using zlib.

As indicated in the header, the remainder of the file contains compressed data containing the information about each inventory item. The uncompressed equivalent is described as the Plain Text Format.

Plain Text Format

DocInventories (like sphobjinv) can remove the compression of the objects.inv file, storing a plain text version of the objects.inv in a .txt format.

It has the same four-line header as the Sphinx Inventory Format (up to a small variation in the fourth line to indicate that the file is no longer compressed). Then, for each InventoryItem, it contains a single line of the form

<name> <domain>:<role> <priority> <uri> <dispname>

Note that DocInventories internally uses the text/x-intersphinx MIME type for the .txt extension, as text/plain is used for the plain text representation of the Inventory object in the Julia REPL (what you see when you type display(inventory)).

TOML Format

The TOML format is a text output format that is optimized for human readability. The format is unique to the DocInventories package. It starts with a header section of the form

# DocInventory version 1
project = "<project>"
version = "<version>"

The comment in the first line is mandatory and identifies the file as containing inventory data in the format described here.

The project line must specify the name of the project described by the inventory. It is mandatory. The version line may specify the version of the project. It is optional, but recommended.

After that, each InventoryItem is represented by a multi-line block of the form

[[<domain>.<role>]]
name = "<name>"
uri = "<uri>"
dispname = "<dispname>"
priority = <priority>

The four lines for name, uri, dispname, and priority may occur in any order. Also, for items with the default priority (-1 for the std domain, 1 otherwise), the priority line may be omitted. If dispname is equal to name (usually indicated by dispname="-"), the dispname line may also be omitted.

The item-blocks may be grouped/separated by blank lines. In .toml files generated by DocInventories.save("inventory.toml", inventory) items will be grouped into blocks with the same [[<domain>.<role>]] with a blank line between each block.

Any TOML parser should read a .toml file with the above structure into a nested dictionary, so that item_dict = toml_data[domain][role][i] corresponds to the i'th inventory item with the given domain and role. That item_dict will then map "name", "uri", and potentially "dispname" and "priority" to their respective values.

A compressed TOML file can be written with, e.g., DocInventories.save("inventory.toml.gz", inventory). With compression, the size of the file should be comparable (albeit slightly larger) than the compressed objects.inv format.

Size Comparison

In the following table, we compare the size of the inventory file of different projects in kilobytes, for the various output formats.