# \[ANN\] Documenter v1.3.0: Inventories

**URL:** https://discourse.julialang.org/t/ann-documenter-v1-3-0-inventories/111139
**Category:** Package Announcements
**Tags:** announcement, documentation, documenter
**Created:** [March 4, 2024, 4:02pm UTC](https://discourse.julialang.org/t/ann-documenter-v1-3-0-inventories/111139 "2024-03-04T16:02:13Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [March 4, 2024, 4:02pm UTC](https://discourse.julialang.org/t/ann-documenter-v1-3-0-inventories/111139/1 "2024-03-04T16:02:14Z")

</div>

We are happy to announce the release of Documenter 1.3.0.

## Features and Improvements

This release features a number of quality-of-life improvements and bugfixes related to the search, thanks to the efforts of @Lilith and @Hetarth02. You should find Documenter’s search an order of magnitude faster.

An experimental new user-facing feature in Documenter 1.3.0 is a new `CollapsedDocStrings` key in the `@meta` block of each page. [Back in Documenter 1.0](https://discourse.julialang.org/t/ann-documenter-1-0/103888/8), we added the ability to manually collapse any docstring in the documentation:

![collapse_manual](https://global.discourse-cdn.com/julialang/original/3X/1/d/1d97c78c3dd3c5e644e0d1ffe97eca69c63fcf32.gif)

Now, you additionally have the ability to add a `@meta` block like

````julia-auto
```@meta
CollapsedDocStrings = true
```

````

to the top of any `.md` file in your documentation. This will cause all docstrings on that page to be collapsed after the page loads:

![collapse_automatic](https://global.discourse-cdn.com/julialang/original/3X/7/a/7a37b9ee2511f3212c5962d88bf0ee6ec2c195ef.gif)

This should make certain API documentation pages easier to work with. Previously, you might have used an [`@index` block](https://documenter.juliadocs.org/stable/man/syntax/#@index-block) to give an overview, followed by an [`@autodocs` block](https://documenter.juliadocs.org/stable/man/syntax/#@autodocs-block) for the full docstrings. Now, an `@autodocs` block on a page with `CollapsedDocStrings = true` would be sufficient.

## Inventory Writing

However, the most significant change in this release is not user-facing. `Documenter` will now automatically write an `objects.inv` “inventory” file whenever it generates the HTML documentation. The format of this file is taken from the [Sphinx project](https://www.sphinx-doc.org/en/master/index.html), which is the equivalent of `Documenter.jl` in the Python universe (i.e., the documentation generator for virtually all Python packages and the Python project itself). The `objects.inv` file contains the name of all pages, section headers, and docstrings in the project and maps them to a URL within the rendered documentation. There is a new package, [`DocInventories.jl`](https://github.com/JuliaDocs/DocInventories.jl), to work with these files programmatically and to convert them to and from a more human-readable `inventory.toml` format.

In the future, the inventory file will allow for any two Documenter-based documentations to link to each other (and between Documenter and Sphinx). In Sphinx, there has long been the widely used [Intersphinx plugin](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) to enable this. For `Documenter`, there is an equivalent [`DocumenterInterLinks.jl`](https://github.com/JuliaDocs/DocumenterInterLinks.jl) package under development. If you are feeling adventurous, you can use that package right now. However, the usefulness of `DocumenterInterLinks` is somewhat limited by the lack of projects that already have an inventory.

For this exact reason, we would ask you to **make sure you are building your documentation with `Documenter v1.3.0` as soon as possible**. If you haven’t set a compat bound for `Documenter` in your `docs/Project.toml` file (or use the recommended `Documenter = "1"`), you should get the update automatically, and you simply have to push a commit to get an `objects.inv` file at least in the `dev` version of your documentation. If, for any reason, you are still using `Documenter < "1.0"` and cannot update, the inventory-writing feature has also been packported to a separate package [`DocumenterInventoryWritingBackport.jl`](https://github.com/JuliaDocs/DocumenterInventoryWritingBackport.jl), which is compatible all the way back to the ancienct `Documenter = "0.25"`. Thus, there is no excuse not to enable inventory writing for your documentation right now. All you have to do is to add `DocumenterInventoryWritingBackport` to your `docs/Project.toml` and add `using DocumenterInventoryWritingBackport` in your `docs/make.jl` file. Simply loading the package will ensure that an inventory file is written.

The `object.inv` contains the project version as metadata. This should be detected automatically. If you have a non-standard project setup (like a monorepo), or you maintain your documentation in a separate repository from the actual project (like the [SciMLDocs](https://github.com/SciML/SciMLDocs)), you may have to set the new `inventory_version` option in the [`HTML`](https://documenter.juliadocs.org/stable/lib/internals/writers/#Documenter.HTMLWriter.HTML) settings that you pass to [`makedocs`](https://documenter.juliadocs.org/dev/lib/public/#Documenter.makedocs) to ensure that the version is correct. If you are building the documentation with `Julia >= "1.9"`, the [`pkgversion`](https://docs.julialang.org/en/v1/base/base/#Base.pkgversion-Tuple%7BModule%7D) function might be useful for obtaining the correct version (or you can manually extract it from your main `Project.toml`). You may also set `inventory_version` manually to avoid any possibility of `Documenter` detecting an incorrect version, or to avoid the `@info` message associated with the automatic detection.

If you would like to add an inventory to an _existing_ release of your package (which we would encourage you to do if you are not planning a new release in the near future), we would like to remind you that `Documenter` ignores the “build metadata” in a tag name, i.e., any suffix attached to a version string with `+`. Thus, if you tag, e.g., `v0.1.0+doc1`, then in the CI run that builds your documentation, `Documenter` will deploy that documentation to overwrite the files in an existing `v0.1.0` folder. You could use that same trick here to add an inventory, e.g., to an existing `v0.1.0` release of your package:

- Create a new branch based on the existing release tag, e.g., `git checkout -b v0.1.0-add-inventory v0.1.0`
- Add the `DocumenterInventoryWritingBackport` package to your `docs/Project.toml` and load it in `docs/make.jl`
- Build your documentation locally to test that it builds correctly and produces an `objects.inv` file
- Commit your changes to the `v0.1.0-add-inventory` branch
- Create a new tag (`git tag v0.1.0+inv`) and push it (`git push --tags`)
- Let your CI take care of building the documentation and overwriting the existing `v0.1.0` documentation with the new version that contains the inventory

There will be a separate announcement of the [`DocumenterInterLinks.jl`](https://github.com/JuliaDocs/DocumenterInterLinks.jl) package when we feel that it is ready for prime time. Specifically, the documentation of the Julia project itself [should also be built with the new version of `Documenter`](https://github.com/JuliaLang/julia/pull/53571), so as to have an inventory file that allows any project to link to the docstrings of `stdlib` functions.