Feature: modernize API documentation

* migrate from the old, unmaintained "asciidoc-py" tool to the new "asciidoctor" generator
* migrate from asciidoc-py syntax to the modern Asciidoc syntax (especially page titles and section titles)
* remove the need of "xmlto" utility to create the manpage output; use asciidoctor for that
* add HTML output support to the doc/Makefile by using asciidoctor
* change API documentation files extension from .txt to .adoc to make it more explicit that they are Asciidoc-encoded (as a bonus several IDE plugins will autodetect the .adoc format as Asciidoc)
* remove asciidoc.conf: asciidoctor does not support that; this also required replacing the macro linkzmq into all documentation pages
* add a new Github action CI do deploy to Github Pages the static HTMLs produced by Asciidoctors
* removed references to the "xmlto" and "a2x" tools from the build and packaging systems: Asciidoctor can convert the documentation directly to e.g. pdf (via extended converters) and anyway there was no code/target for using "xmlto" and "a2x" tools anyway

.github/workflows/CI.yaml

@@ -25,7 +25,7 @@ jobs:
             ENABLE_DRAFTS: ON
           - os: ubuntu-latest
             BUILD_TYPE: default
-            PACKAGES: asciidoc xmlto
+            PACKAGES: asciidoctor
             DRAFT: disabled
             POLLER: select
           - os: ubuntu-latest

.github/workflows/Docs.yaml

@@ -0,0 +1,50 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy API docs content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["feature/asciidoctor"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      ## libzmq-specific CI/CD ##
+      - name: Install AsciiDoctor
+        run: sudo apt install -y asciidoctor
+      - name: Convert AsciiDoc with AsciiDoctor into HTML
+        run: ./autogen.sh && ./configure && make --directory=doc
+
+      ## boilerplate steps to publish github Pages ##
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'doc/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

CMakeLists.txt

@@ -770,7 +770,7 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Darwin")
   add_definitions(-D_DARWIN_C_SOURCE)
 endif()
 
-find_package(AsciiDoc)
+find_package(AsciiDoctor)
 
 cmake_dependent_option(WITH_DOC "Build Reference Guide documentation(requires DocBook)" ON "ASCIIDOC_FOUND;NOT WIN32"
                        OFF) # Do not build docs on Windows due to issues with symlinks
@@ -1256,25 +1256,16 @@ option(WITH_DOCS "Build html docs" ON)
 if(WITH_DOCS)
   file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc)
   file(
-    GLOB docs
+    GLOB asciidoc_files
     RELATIVE ${CMAKE_CURRENT_BINARY_DIR}/
-    "${CMAKE_CURRENT_SOURCE_DIR}/doc/*.txt")
-  set(html-docs)
-  foreach(txt ${docs})
-    string(REGEX REPLACE ".*/(.*)\\.txt" "\\1.html" html ${txt})
-    set(src ${txt})
-    set(dst doc/${html})
-    if(WITH_DOC)
-      add_custom_command(
-        OUTPUT ${dst}
-        COMMAND ${ASCIIDOC_EXECUTABLE} -d manpage -b xhtml11 -f ${CMAKE_CURRENT_SOURCE_DIR}/doc/asciidoc.conf
-                -azmq_version=${ZMQ_VERSION} -o ${dst} ${src}
-        DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${src}
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "Generating ${html}")
-      list(APPEND html-docs ${CMAKE_CURRENT_BINARY_DIR}/${dst})
-    endif()
-  endforeach()
+    "${CMAKE_CURRENT_SOURCE_DIR}/doc/*.adoc")
+  string(REPLACE ".txt" ".html" html_files ${asciidoc_files})
+  add_custom_command(
+    OUTPUT ${html_files}
+    COMMAND asciidoctor -b html -azmq_version=${ZMQ_VERSION} *.adoc
+    DEPENDS ${asciidoc_files}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating ${html}")
 endif()
 
 if(ZMQ_BUILD_FRAMEWORK)

acinclude.m4

@@ -89,7 +89,7 @@ dnl # Check whether to build documentation and install man-pages
 dnl ##############################################################################
 AC_DEFUN([LIBZMQ_CHECK_DOC_BUILD], [{
 
-    # Man pages are built/installed if asciidoc and xmlto are present
+    # Man pages are built/installed if asciidoctor and xmlto are present
     #   --with-docs=no overrides this
     AC_ARG_WITH([docs],
         AS_HELP_STRING([--without-docs],
@@ -109,14 +109,13 @@ AC_DEFUN([LIBZMQ_CHECK_DOC_BUILD], [{
         libzmq_build_doc="yes"
         libzmq_install_man="yes"
         # Check for asciidoc and xmlto and don't build the docs if these are not installed.
-        AC_CHECK_PROG(libzmq_have_asciidoc, asciidoc, yes, no)
-        AC_CHECK_PROG(libzmq_have_xmlto, xmlto, yes, no)
-        if test "x$libzmq_have_asciidoc" = "xno" -o "x$libzmq_have_xmlto" = "xno"; then
+        AC_CHECK_PROG(libzmq_have_asciidoctor, asciidoctor, yes, no)
+        if test "x$libzmq_have_asciidoctor" = "xno"; then
             libzmq_build_doc="no"
             # Tarballs built with 'make dist' ship with prebuilt documentation.
             if ! test -f doc/zmq.7; then
                 libzmq_install_man="no"
-                AC_MSG_WARN([You are building an unreleased version of 0MQ and asciidoc or xmlto are not installed.])
+                AC_MSG_WARN([You are building an unreleased version of 0MQ and asciidoctor is not installed.])
                 AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
             fi
         fi

builds/cmake/Modules/FindAsciiDoctor.cmake

@@ -0,0 +1,23 @@
+# - Find Asciidoctor
+# this module looks for asciidoctor
+#
+# ASCIIDOCTOR_EXECUTABLE - the full path to asciidoc
+# ASCIIDOCTOR_FOUND - If false, don't attempt to use asciidoc.
+set (PROGRAMFILESX86 "PROGRAMFILES(X86)")
+
+find_program(ASCIIDOCTOR_EXECUTABLE asciidoctor asciidoctor
+             PATHS "$ENV{ASCIIDOCTOR_ROOT}"
+                   "$ENV{PROGRAMW6432}/asciidoctor"
+                   "$ENV{PROGRAMFILES}/asciidoctor"
+                   "$ENV{${PROGRAMFILESX86}}/asciidoctor")
+
+find_program(A2X_EXECUTABLE a2x
+             PATHS "$ENV{ASCIIDOCTOR_ROOT}"
+                   "$ENV{PROGRAMW6432}/asciidoctor"
+                   "$ENV{PROGRAMFILES}/asciidoctor"
+                   "$ENV{${PROGRAMFILESX86}}/asciidoctor")
+
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_ARGS(AsciiDoctor REQUIRED_VARS ASCIIDOCTOR_EXECUTABLE)
+mark_as_advanced(ASCIIDOCTOR_EXECUTABLE)

configure.ac

@@ -76,10 +76,6 @@ PKG_PROG_PKG_CONFIG
 m4_pattern_forbid([^PKG_[A-Z_]+$], [missing some pkg-config macros (pkg-config package)])
 
 # Libtool configuration for different targets. See acinclude.m4
-AC_ARG_VAR([XMLTO], [path to xmlto command])
-AC_PATH_PROG([XMLTO], [xmlto])
-AC_ARG_VAR([ASCIIDOC], [path to asciidoc command])
-AC_PATH_PROG([ASCIIDOC], [asciidoc])
 LIBZMQ_CONFIG_LIBTOOL
 AC_LIBTOOL_WIN32_DLL
 AC_PROG_LIBTOOL

doc/Makefile.am

@@ -1,7 +1,8 @@
 #
 # documentation
 #
-MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_close.3 \
+MAN3 = \
+    zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3 zmq_close.3 \
     zmq_ctx_new.3 zmq_ctx_term.3 zmq_ctx_get.3 zmq_ctx_set.3 zmq_ctx_shutdown.3 \
     zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_init_buffer.3 \
     zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \
@@ -22,45 +23,58 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_connect_peer.3 zmq_disconnect.3
     zmq_atomic_counter_inc.3 zmq_atomic_counter_dec.3 \
     zmq_atomic_counter_value.3 zmq_atomic_counter_destroy.3
 
-MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
+MAN7 = \
+    zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
     zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7 zmq_vmci.7 zmq_udp.7 \
     zmq_gssapi.7
 
-MAN_DOC =
+# MAN_ADOC contains all original Asciidoc files from git repo
+MAN_ADOC = $(MAN3:%.3=%.adoc) $(MAN7:%.7=%.adoc)
 
-MAN_TXT = $(MAN3:%.3=%.txt)
-MAN_TXT += $(MAN7:%.7=%.txt)
-MAN_HTML =
+# MAN_DOC contains all the MANUAL PAGES (generated from asciidoc files)
+MAN_DOC = $(MAN3) $(MAN7) 
 
-MAINTAINERCLEANFILES =
+# MAN_HTML contains all the HTML PAGES (generated from asciidoc files)
+MAN_HTML = $(MAN_ADOC:%.adoc=%.html)
 
-EXTRA_DIST = asciidoc.conf $(MAN_TXT)
+MAINTAINERCLEANFILES =
+EXTRA_DIST = $(MAN_ADOC)
 
-if INSTALL_MAN
-MAN_DOC += $(MAN1) $(MAN3) $(MAN7)
-dist_man_MANS = $(MAN_DOC)
-MAINTAINERCLEANFILES += $(MAN_DOC)
-endif
 
+#
+# BUILD_DOC is set when Asciidoctor has been found
+# Declare here all the rules to produce documentation from .adoc files
+#
 if BUILD_DOC
-MAN_HTML += $(MAN_TXT:%.txt=%.html)
-EXTRA_DIST += $(MAN_HTML)
-MAINTAINERCLEANFILES += $(MAN_HTML)
-
-SUFFIXES=.html .txt .xml .3 .7
-
-.txt.html:
-	asciidoc -d manpage -b xhtml11 -f $(srcdir)/asciidoc.conf \
-		-azmq_version=@PACKAGE_VERSION@ -o$@ $<
-.txt.xml:
-	asciidoc -d manpage -b docbook -f $(srcdir)/asciidoc.conf \
-		-azmq_version=@PACKAGE_VERSION@ -o$@ $<
-.xml.1:
-	xmlto man $<
-.xml.3:
-	xmlto man $<
-.xml.7:
-	xmlto man $<
-endif
+
+EXTRA_DIST += $(MAN_HTML) $(MAN_DOC)
+MAINTAINERCLEANFILES += $(MAN_HTML) $(MAN_DOC)
+SUFFIXES=.html .adoc .3 .7
+
+.adoc.html: 
+	asciidoctor -b html -azmq_version=@PACKAGE_VERSION@  $<
+.adoc.3:
+	asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@  $<
+.adoc.7:
+	asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@  $<
 
 dist-hook : $(MAN_DOC) $(MAN_HTML)
+
+# To help publishing HTML files into github Pages, we indicate github that the "zmq.html" page is the index page;
+# that page contains a link to all other documentation pages
+all-local : $(MAN_DOC) $(MAN_HTML)
+	ln -sf zmq.html index.html
+
+clean-local :
+	rm -f $(MAN3) $(MAN7) $(MAN_HTML)
+
+endif
+
+
+
+#
+# INSTALL_MAN is set when BUILD_DOC was set and additionally the manpages need to be installed
+#
+if INSTALL_MAN
+dist_man_MANS = $(MAN_DOC)
+endif