Skip to content

Redesign doc building options

Richard Laager requested to merge rlaager/ntpsec:doc-building-options into master

Prior to recent changes (i.e. in the last release):

  • HTML docs were not built by default, even if you had asciidoc installed. You had to explicit opt-in with --enable-doc.
  • Man pages were built by default if you had asciidoc installed. If asciidoc was not installed, the build continued without building man pages. --disable-manpage could optionally be used (e.g. to speed the build).
  • CentOS 6 had too old of an asciidoc, but the build continued without building man pages.

After recent changes (see !1037 (merged)):

  • HTML docs were built by default. If you did not have asciidoc(tor) installed, waf configure stopped with an error telling you to explicitly pass --disable-doc.
  • Man pages were built by default. If you did not have asciidoc(tor) installed, waf configure stopped with an error telling you to explicitly pass --disable-manpage.
  • CentOS 6 had too old of an asciidoc. The build would stop with an error telling you to explicitly pass --disable-manpage.

Relative to the previous state, this improved things by:

  • being consistent
  • building the useful docs by default
  • failing loudly so you can't accidentally miss building man pages

but:

  • broke any build scripts (e.g. in distro packages) passing --enable-doc
  • requires CentOS 6 users to pass --disable-doc and --disable-manpage
  • requires users to either install asciidoc(tor) or pass --disable-doc and --disable-manpage

Now, with this MR:

  • HTML docs are built by default if you have asciidoc(tor) installed. If asciidoc(tor) is not installed, the build continues without building HTML docs. --disable-doc can optionally be used (e.g. to speed the build). --enable-doc can optionally be used (e.g. to require that docs be built).
  • Man pages are built by default if you have asciidoc(tor) installed. If asciidoc(tor) is not installed, the build continues without building man pages. --disable-manpage can optionally be used (e.g. to speed the build). --enable-manpage can optionally be used (e.g. to require that docs be built).
  • CentOS 6 has too old of an asciidoc, but the build continues without building man pages.

Relative to the original state, this keeps the following improvements:

  • being consistent
  • building the useful docs by default (but only when asciidoc(tor) is installed)

and allows via --enable-doc and --enable-manpage (but no longer defaults to):

  • failing loudly so you can't accidentally miss building docs and/or man pages

Relative to the intermediate state, it has the following advantages:

  • build scripts with --enable-doc still work
  • CentOS 6 users do not have to pass --disable-doc and --disable-manpage
  • users are not required to install asciidoc(tor) or pass --disable-doc and --disable-manpage

Additionally:

  • The configure script now outputs a "Build Docs" line to match the "Build Manpages" line.
  • The code for the "Build Manpages" output and the actual decision check the same thing, which is now a single boolean.

The CI runners are all explicitly enabling or disabling docs as desired, so those that are supposed to be building docs cannot silently fail (e.g. if we change the minimum asciidoc(tor) version requirements).

One case where you may want to require that docs be built would be a distro package. That way, if upstream NTPsec raises the minimum required asciidoc(tor) version, you will either stay working or fail hard, rather than silently skipping building the docs. The CI runners are another example where "fail loudly" behavior is desirable.

Here is the expected behavior, where "Doc" is Y = --enable-doc vs N = --disable-doc, "Man" is the same for --enable-manpage / --disable-manpage, and "ADI" is whether you have a supported asciidoc(tor) processor installed:

  Doc Man ADI
1  Y   Y   Y   WORKS, builds both
2  Y   Y   N   FAILS with remove --enable-doc, remove enable-manpage
3  Y   N   Y   WORKS, builds docs and not man pages
4  Y   N   N   FAILS with remove --enable-doc
5  N   Y   Y   WORKS, builds man pages and not docs
6  N   Y   N   FAILS with remove --enable-manpage
7  N   N   Y   WORKS with "unnecessary" and no version checks
8  N   N   N   WORKS with "unnecessary" and no version checks
9  Y   Y   *   * = no a2x or xsltproc; FAILS with a2x/xsltproc not found, remove --enable-manpage
A  N   Y   *   * = no a2x or xsltproc; FAILS with a2x/xsltproc not found, remove --enable-manpage

The behavior for not specifying --enable-doc and/or --enable-manpage is that it autodetects whether you have a supported processor. In that case, it falls into one of the "WORKS" categories.

I tested and verified all the combinations with this shell loop, once without asciidoc, once with it, and once with it installed but /usr/bin/xsltproc moved out of the way:

for i in --enable-doc --disable-doc "" ; do for j in --enable-manpage --disable-manpage "" ; do rm -rf build ; echo python3 waf configure $i $j ; python3 waf configure $i $j 2>&1 | grep -Ei "(ascii|Build (Doc|Man))" ; python3 waf build | grep -E "(ntp.keys-man.adoc|docs/ntpd.adoc)" ; done ; done
Edited by Richard Laager

Merge request reports