Skip to content

[#1147] Fail the doc build when a page leaves an AsciiDoc attribute unresolved #1148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vharseko wants to merge 2 commits into
base: master
Choose a base branch
from
Open

[#1147] Fail the doc build when a page leaves an AsciiDoc attribute unresolved #1148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
38de0b5
[#1147] Fail the doc build when a page leaves an AsciiDoc attribute u…
vharseko Oct 1, 2026
e4633ee
[#1147] Check literal table cells and escaped or intrinsic references…
vharseko Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions opendj-doc-generated-ref/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,24 @@
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<docTargetVersion>${project.version}</docTargetVersion>
<sdkDocTargetVersion>${project.version}</sdkDocTargetVersion>
<!-- The Asciidoctor of asciidoctor-maven-plugin, which the tests of the doc extensions also run on -->
<asciidoctorj.version>2.5.11</asciidoctorj.version>
</properties>

<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.openidentityplatform.commons</groupId>
<artifactId>build-tools</artifactId>
<scope>test</scope>
</dependency>
</dependencies>


<build><finalName>${project.groupId}.${project.artifactId}</finalName>
<plugins>
Expand Down Expand Up @@ -356,6 +372,34 @@
</execution>
</executions>
</plugin>

<!-- A pom module compiles and runs no tests by itself: these test the Asciidoctor extensions -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>compile-extension-tests</id>
<phase>test-compile</phase>
<goals>
<goal>testCompile</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<executions>
<execution>
<id>test-extensions</id>
<phase>test</phase>
<goals>
<goal>test</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Expand Down Expand Up @@ -603,7 +647,66 @@
<outputDirectory>${project.build.directory}/asciidoc/man-pages</outputDirectory>
</configuration>
</execution>
<!--
Fail the build when a page would publish an attribute reference as literal
text, which neither the PDF below nor the Antora site reports. Every .adoc of
the pre-processed sources is rendered on its own, the way Antora renders each
chapter as a page, so a page that relies on an attribute another chapter
defines fails here although the PDF book resolves it. attribute-missing=warn
reports a reference to an attribute that is not defined;
literal-attribute-references.rb reports one in a verbatim block without
subs="+attributes" or in a literal table cell. The HTML output is thrown away.
LiteralAttributeReferencesTest renders its pages with the configuration of
this execution.

The plugin stops at the first page that fails, so fix it and run again to see
the next one: mvn -Pdistribution-unix,man-pages -pl opendj-doc-generated-ref
asciidoctor:process-asciidoc@check-attribute-references, after a build of this
module (both profiles activate by themselves only on Linux). Asciidoctor names
no file for a missing attribute: it is the page of the "Converted" line that
follows the warning. A literal {name} in text is written \{name}.

Maven project properties are attributes here (product.name is {product-name})
but not on the site, so a page that uses one passes this check and still shows
the braces there.
-->
<execution>
<id>check-attribute-references</id>
<phase>verify</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<requires>
<require>${project.basedir}/src/main/resources/asciidoc/extensions/nested-open-block.rb</require>
<require>${project.basedir}/src/main/resources/asciidoc/extensions/literal-attribute-references.rb</require>
</requires>
<backend>html5</backend>
<sourceDirectory>${project.build.directory}/asciidoc/source</sourceDirectory>
<outputDirectory>${project.build.directory}/asciidoc/attribute-check</outputDirectory>
<preserveDirectories>true</preserveDirectories>
<relativeBaseDir>true</relativeBaseDir>
<sourcemap>true</sourcemap>
<attributes>
<attribute-missing>warn</attribute-missing>
<literal-attribute-sources>${project.build.directory}/asciidoc/source</literal-attribute-sources>
</attributes>
<logHandler>
<failIf>
<severity>WARN</severity>
<containsText>attribute</containsText>
</failIf>
</logHandler>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
</dependencies>
</plugin>

<!-- Format man pages -->
Expand Down
6 changes: 3 additions & 3 deletions opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-monitoring.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ SNMP is not enabled by default. SNMP-based monitoring depends on OpenDMK, which

To run the OpenDMK installer, use the self-extracting .jar:

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ java -jar ~/Downloads/opendmk-1.0-b02-*.jar
$ cd ~/Downloads/
Expand Down Expand Up @@ -150,7 +150,7 @@ $ dsconfig \
----
Use a command such as `snmpwalk` to check that the SNMP listen port works:

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161
SNMPv2-SMI::mib-2.66.1.1.1.1 = STRING: "OpenDJ {opendj-version}..."
Expand Down Expand Up @@ -248,7 +248,7 @@ OpenDJ comes with two commands for monitoring server processes and tasks. The `s

The `status` command takes administrative credentials to read the configuration, as does the control panel:

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ status --bindDN "cn=Directory Manager" --bindPassword password

Expand Down
4 changes: 2 additions & 2 deletions opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-pwd-policy.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2026 3A Systems LLC.
////

:figure-caption!:
Expand Down Expand Up @@ -1009,7 +1009,7 @@ $ ldappasswordmodify \
--authzID "u:bjensen" \
--newPassword '!ABcd$%^'
----
In the preceding example, the character set of ASCII punctuation, ``!\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~``, is hard to read because of all the escape characters. In practice it can be easier to enter sequences like that by using `dsconfig` in interactive mode, and letting it do the escaping for you. You can also use the `--commandFilePath {path}` option to save the result of your interactive session to a file for use in scripts later.
In the preceding example, the character set of ASCII punctuation, ``!\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~``, is hard to read because of all the escape characters. In practice it can be easier to enter sequences like that by using `dsconfig` in interactive mode, and letting it do the escaping for you. You can also use the `--commandFilePath \{path}` option to save the result of your interactive session to a file for use in scripts later.

An attempt to set an invalid password fails as shown in the following example:

Expand Down
2 changes: 1 addition & 1 deletion opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -808,7 +808,7 @@ OpenDJ maintains historical information about changes in order to bring replicas

When you cannot resolve a problem yourself, and want to ask for help, clearly identify the problem and how you reproduce it, and also the version of OpenDJ you use to reproduce the problem. The version includes both a version number and also a build time stamp:

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ dsconfig --version
OpenDJ {opendj-version}
Expand Down
16 changes: 8 additions & 8 deletions opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,7 +383,7 @@ If you do not start the server during installation, you can use the `/path/to/op
. Run the `status` command, described in xref:../reference/admin-tools-ref.adoc#status-1[status(1)] in the __Reference__, to make sure your OpenDJ server is working as expected as shown in the following example:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ /path/to/opendj/bin/status

Expand Down Expand Up @@ -437,7 +437,7 @@ On Debian and related Linux distributions such as Ubuntu, you can install OpenDJ
. Install the OpenDJ directory server package. Use `apt-get install ./<file>.deb` (rather than `dpkg -i`) so the required Java runtime dependency (`default-jre-headless`) is resolved and installed automatically:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ sudo apt-get install ./opendj_{opendj-version}-1_all.deb
----
Expand All @@ -463,7 +463,7 @@ $ sudo systemctl start opendj
. (Optional) Check OpenDJ directory server status:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ systemctl is-active opendj
active
Expand Down Expand Up @@ -525,7 +525,7 @@ Password:
. Install the OpenDJ directory server package. Use `dnf install ./<file>.rpm` (rather than `rpm -i`) so the required Java runtime dependency (`java-headless >= 11`) is resolved and installed automatically:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
# dnf install ./opendj-{opendj-version}-1.noarch.rpm
Post Install - initial install
Expand All @@ -552,7 +552,7 @@ To see basic server configuration status and configuration you can launch
. (Optional) Check OpenDJ directory server status:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
# systemctl is-active opendj
active
Expand Down Expand Up @@ -623,7 +623,7 @@ The package is not code-signed, so Windows SmartScreen or User Account Control m
* Silent: run the following command (optionally set the installation directory with the `OPENDJ` property):
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\opendj"
----
Expand Down Expand Up @@ -701,7 +701,7 @@ If you have multiple servers to install, consider scripting creation of the prop
. Prepare an installation script:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ cat /net/install/dj/1/setup.sh
#!/bin/sh
Expand Down Expand Up @@ -756,7 +756,7 @@ END_OF_COMMAND_INPUT
. Run your installation script:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ /net/install/dj/1/setup.sh
Archive: /net/install/dj/opendj-{opendj-version}.zip
Expand Down
2 changes: 1 addition & 1 deletion opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ C:\path\to\opendj\bat> windows-service.bat --disableService
. Uninstall the package, either through __Settings > Apps__ (or __Control Panel > Programs and Features__) by selecting OpenDJ and choosing Uninstall, or from the command-line:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
C:\> msiexec /x opendj-{opendj-version}.msi /quiet
----
Expand Down
4 changes: 2 additions & 2 deletions opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ C:\path\to\opendj\bat> windows-service.bat --enableService
====
The following example upgrades an OpenDJ 2.6.3 directory server, backing up the current server directory in case the upgrade process fails. In this example, the server properties are updated to use Java 11, and the Local DB backend is migrated to a JE backend:

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ cd /path/to/
$ sed -e "s/default.java-home=.*/default.java-home=\/path\/to\/jdk11/" \
Expand Down Expand Up @@ -268,7 +268,7 @@ A server started with `start-ds.bat` rather than as a service is refused in the
. Install the newer package (GUI or silent). The installer detects the existing installation — the location recorded in the registry by a previous x64 package, or the default directory of the older 32-bit package (`C:\Program Files (x86)\OpenDJ`) — and installs into the same directory, so your configured instance data (`config`, `db`, `logs`) is kept and only the program files are replaced. If the older server was installed in a custom directory the installer cannot detect, select that directory in the wizard or pass it explicitly on the command line: rather than installing a fresh server into the default directory while emptying the old one, the installer refuses to continue whenever nothing has recorded where the old server lives and the directory it is about to install into holds no OpenDJ server -- which also catches a mistyped directory name. That refusal also covers an old server that really is installed in `C:\Program Files\OpenDJ`, because the 32-bit packages recorded no location at all — and that one case the wizard cannot resolve: choosing the default directory in the wizard leaves the installer with the same values it would have had if you had chosen nothing, so pass `OPENDJ` on the command line instead — it can be given with or without `/quiet`, so a wizard installation takes it just as a silent one does. The installer further refuses to install into a directory other than the one it detected, unless the directory you name holds an OpenDJ server itself (see the note below): it replaces an installation in place and cannot move one, so uninstall the existing server first if you want it somewhere else.
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\path\to\opendj"
----
Expand Down
4 changes: 2 additions & 2 deletions opendj-doc-generated-ref/src/main/asciidoc/man-pages/man-windows-service.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
information: "Portions Copyright [year] [name of copyright owner]".

Copyright 2015-2016 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2026 3A Systems LLC.

////

Expand All @@ -28,7 +28,7 @@
windows-service - register OpenDJ as a Windows Service

== Synopsis
`windows-service` {options}
`windows-service` \{options}

== Description
This utility can be used to run OpenDJ directory server as a Windows Service.
Expand Down
2 changes: 1 addition & 1 deletion ...-doc-generated-ref/src/main/asciidoc/server-dev-guide/chap-writing-plugins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ $ mvn install
. Install the example plugin in OpenDJ directory server:
+

[source, console, subs="attributes"]
[source, console, subs="+attributes"]
----
$ cd /path/to/opendj

Expand Down
Loading
Loading