From 267e856494c5cd7619c8521b64c6fb3a38930ecb Mon Sep 17 00:00:00 2001
From: Francesco Montorsi <f18m@users.noreply.github.com>
Date: Thu, 2 Nov 2023 21:44:34 +0100
Subject: [PATCH] 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       | 37 +++++++++++++++++++++++++++++++++++++
 doc/Makefile.am         | 16 +++++++---------
 doc/create_page_list.sh | 20 ++++++++++++++++++++
 3 files changed, 64 insertions(+), 9 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100755 doc/create_page_list.sh

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..fec038e2
--- /dev/null
+++ b/.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
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7d143e41..3d5b6835 100644
--- a/doc/Makefile.am
+++ b/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 >$@
-	for adocfile in $(ASCIIDOC_DOC_WITHOUT_INDEX); do \
-		noext=$${adocfile//.adoc/}; \
-		echo "* xref:$${adocfile}[$${noext}]" >> $@; \
-	done
+	$(srcdir)/create_page_list.sh "$@" "$(abs_srcdir)"
 
 # 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)
 
diff --git a/doc/create_page_list.sh b/doc/create_page_list.sh
new file mode 100755
index 00000000..64b6a33a
--- /dev/null
+++ b/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