Doc build should show error when asciidoc attributes are not resolved

[dedemorton]

Right now, if the doc build cannot resolve an asciidoc attribute, the attribute and the text that follows it are dropped from the docs. We've had multiple situations where content was missing from the doc, but we didn't know until a user or someone internal noticed the problem.

[clintongormley]

This is just how asciidoc works, unfortunately. If an attribute is undefined, then the line that contains it is ignored.

I don't know of a way around this.

[dedemorton]

@clintongormley Then maybe we need to find a solution outside of asciidoc. Even a rudimentary script that does something like the following would uncover problems.

For each book:

1. search for all :attributes: and compile a list
2. search for all {attributes} and compile a list
3. For each item in the second list, make sure a corresponding definition exists in the first list

It wouldn't be 100% accurate because it wouldn't take order into consideration, but it would pick up most, if not all, unresolved attribute references.

Is this feasible? If this is too heavy-weight to run for every build, I'd even be happy to have a script that I can run locally.

[debadair]

Another check to add to the attributes preflighting: make sure there are no attribute references within a bulleted list embedded in a table. They do not resolve & the list items will be blank.

[gtback]

Asciidoctor has an attribute-missing option to control what we want to do. It seems like the Asciidoctor default is to leave the reference intact (skip), so it should be easier to notice them. The default asciidoc.py behavior was to drop the entire line, which of course is not desirable.

There is code to warn on missing attributes, but it's currently commented out. I recommend re-enabling that, at least for branches that we're still actively maintaining, and find and fix any warnings in those branches.

[lcawl]

I can confirm that unresolved attributes are now left in the docs (e.g. elastic/elasticsearch#44249). This is better than the previous behaviour but anything we can do to make it even more obvious when this happens would be great!

[gtback]

This popped up again today in some old branches. I'll prioritize getting this fixed, at least for live branches.

[dedemorton]

I'm guessing this won't be fixed in the legacy docs. As it's quite old and I'm tired of seeing it in my list, I'm closing it.