In which I vent more about Antora

Part 3 of my Hack Week recap

For the sake of giving my original post a consistent structure, and not boring the non-tech-writers who might want to read it with exhaustive detail, I left out additional observations from my experience using Antora.

Writing experience

My next complaint: Antora doesn’t offer a way to set up a watcher or otherwise live-reload changes to the docs as you make them. Additionally, because you're making content changes in a different repo than the one where your site lives, the process for previewing a docs change looks like this:

1. Make a change in <content-repo> and save your file.

2. Commit and push your change.

3. Remove the cache directory in <configuration-repo>.

4. Run the equivalent of a git pull in <configuration-repo>.

5. Rebuild your site.

If you're someone like me, not being able to preview changes easily as you make them slows your writing down and makes you feel like you're going about it blindly. If you're a developer, it likely means you will not preview your changes locally at all.

Features that did not live up to my expectations

The difficult of setting up an Antora project and writing docs in AsciiDoc would be enough by themselves to rule out Antora as a tool for internal docs, but as a bonus, here are a handful of Antora features I was excited about that disappointed me.

Partials

Antora has the concept of partials — the ability to pull text from File A and include it within File B — which is a feature in Sphinx that I miss in our Markdown-based current system. However, one of the best uses of partials is to include excerpts from code files, which Antora doesn't support.

For example, say you want to document your product's configuration.yaml file. Rather than copying the default version of that file into the docs, you can include it directly from the source. Then you don't have to worry about the docs version getting out of date, since it's always pulling from the latest code.

RST:

Configuring the product
=======================

The default `configuration.json` file looks like this after installation:

.. include:: <path>/<to>/configuration.json

Description of properties
-------------------------

* `title`: Set this to your desired title...

Again, this is not currently possible in Antora, though the documentation notes that this will be possible in future releases:

Currently, all of the example files you want to include must live in the examples directory inside the current module. In the future, it will be possible to pull in example source code and files from other locations.

So while having partials is better than nothing, this feature in Antora is currently of limited use.

Navigation files

Navigation files let you define which pages to include and in what order. This is a feature I appreciate, but a) the syntax is fussy and b) you have to provide the title yourself! In Sphinx, you simply specify the filename, and it pulls the title from the file's H1 heading.

Antora:

* xref:overview.adoc[Overview of the Product]
* xref:troubleshooting.adoc[Troubleshooting Your Local Environment]
* xref:tutorials/advanced.adoc[Advanced Tutorial]

RST:

.. toctree::

   overview
   troubleshooting
   tutorials/advanced

Listing files from different components and modules adds more to the Antora syntax, and I didn't even touch different versions.

Pulling content from multiple repositories

At last, the feature I was most excited about: bringing together content from multiple repositories.

I longed for this feature at my last job, when a single product had code spread across multiple repositories and therefore released multiple sets of release notes. I wanted to pull all of these release notes files into the same docs site and was forced to cobble together a build command that checked out each of the repositories, built each docs project separately, and then copied the built files into the right locations. Antora, I thought, could have solved this.

To test this, I simply wanted to include a couple pages from a second repo in my table of contents. I added this to my default navigation file:

.Content from Repo 1
* xref:introduction.adoc[Overview]
* xref:othertopic.adoc[Some topic]

.Content from Eva Test
* xref:evatest:ROOT:guide1.adoc[Guide to topic 1]
* xref:evatest:ROOT:guide2.adoc[Guide to topic 2]

It built fine — but every time I clicked on one of the "evatest" pages in the sidebar, it took me out of the default navigation and loaded a totally different sidebar with a different table of contents. What I really wanted was for all of the pages I specified to be part of a single project, and I never accomplished this.