[ANN] Documenter v1.3.0: Inventories

Package Announcements
, ,
1

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, we added the ability to manually collapse any docstring in the documentation:

collapse_manual

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

```@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

This should make certain API documentation pages easier to work with. Previously, you might have used an @index block to give an overview, followed by an @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, 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, 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 to enable this. For Documenter, there is an equivalent 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, 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), you may have to set the new inventory_version option in the HTML settings that you pass to makedocs to ensure that the version is correct. If you are building the documentation with Julia >= "1.9", the pkgversion 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 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, so as to have an inventory file that allows any project to link to the docstrings of stdlib functions.

43 Likes