Feature: master: integrate with ReadTheDocs (#4614)

* Feature: integrate libzmq with ReadTheDocs

* add readthedocs configuration file to convert Asciidoc files into HTML and HTMLZIP formats using Asciidoctor.js tool (the only Asciidoctor variant available on readthedocs so far)

.readthedocs.yaml

@@ -0,0 +1,37 @@
+#
+# libzmq readthedocs.io integration
+#
+# This configuration file is processed by readthedocs.io to rebuild the
+# libzmq documentation using Asciidoctor, see
+#   https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc
+
+version: "2"
+
+formats:
+  - htmlzip
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    nodejs: "20"
+  # NOTE: as of Nov 2023, build.apt_packages is NOT considered when using build.commands
+  #apt_packages:
+  #  - automake
+  #  - autoconf
+  #  - cmake
+  #  - libtool
+  commands:
+    # install required tools
+    - npm install -g asciidoctor
+
+    # HTML docs
+    # ---------
+    - doc/create_page_list.sh "$(pwd)/doc/__pagelist" "$(pwd)/doc"
+    - asciidoctor --backend html --destination-dir $READTHEDOCS_OUTPUT/html --attribute zmq_version='4.3.6' --attribute zmq_pagelist_dir=$(pwd)/doc doc/*.adoc
+
+    # HTMLZIP docs
+    # ------------
+    # Note that for usability we make sure zip will create a zipfile containing just a flat list of HTML files; 
+    # to achieve that it's important to avoid storing absolute paths when invoking "zip", thus we use -j
+    - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/
+    - cd $READTHEDOCS_OUTPUT/html && zip -j ../htmlzip/zeromq.zip *.html

doc/Makefile.am

@@ -52,21 +52,17 @@ MAINTAINERCLEANFILES += $(HTML_DOC) $(MAN_DOC)
 SUFFIXES=.html .adoc .3 .7
 
 .adoc.html:
-	asciidoctor -b html -azmq_version=@PACKAGE_VERSION@  $<
+	asciidoctor --backend html --attribute zmq_version=@PACKAGE_VERSION@  $<
 .adoc.3:
-	asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@  $<
+	asciidoctor --backend manpage --attribute zmq_version=@PACKAGE_VERSION@  $<
 .adoc.7:
-	asciidoctor -b manpage -azmq_version=@PACKAGE_VERSION@  $<
+	asciidoctor --backend manpage --attribute zmq_version=@PACKAGE_VERSION@  $<
 
 dist-hook : $(MAN_DOC) $(HTML_DOC)
 
 # the following Bash snippet is used to automatically generate an alphabetical list included by index.adoc:
 $(builddir)/__pagelist:
-	echo >$@
+	$(srcdir)/create_page_list.sh "$@" "$(abs_srcdir)"
-	for adocfile in $(ASCIIDOC_DOC_WITHOUT_INDEX); do \
-		noext=$${adocfile//.adoc/}; \
-		echo "* xref:$${adocfile}[$${noext}]" >> $@; \
-	done
 
 # there are a number of constraints in auto-generating files for Asciidoctor:
 # - out-of-tree builds
@@ -75,7 +71,9 @@ $(builddir)/__pagelist:
 # etc, so we have special rules to build the index.html page, which requires auto-generated list of doc pages
 index.html:
 	$(MAKE) $(builddir)/__pagelist
-	asciidoctor -b html -azmq_version=@PACKAGE_VERSION@ -azmq_pagelist_dir=$(abs_builddir) $(srcdir)/index.adoc
+	asciidoctor --backend html \
+        --attribute zmq_version=@PACKAGE_VERSION@ --attribute zmq_pagelist_dir=$(abs_builddir) \
+            $(srcdir)/index.adoc
 
 all-local : $(MAN_DOC) $(HTML_DOC)
 

doc/create_page_list.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# This Bash snippet is used to automatically generate an alphabetical list included by index.adoc
+# It's invoked by at least 2 callers:
+# - the Makefile[.am] for automake builds
+# - the ReadTheDocs pipeline, see .readthedocs.yaml
+
+OUTPUT_FILE="$1"
+ASCIIDOC_DIR="$2"
+
+echo >$OUTPUT_FILE
+for adocfile in $(ls ${ASCIIDOC_DIR}/*.adoc); do
+    adocfile_basename=$(basename ${adocfile})
+
+    # this script is used to produce an Asciidoc snippet that goes inside index.adoc... avoid listing index.adoc itself!
+    if [ "${adocfile_basename}" != "index.adoc" ]; then
+        adocfile_basename_noext=${adocfile_basename//.adoc/}
+        echo "* xref:${adocfile_basename}[${adocfile_basename_noext}]" >>$OUTPUT_FILE
+    fi
+done