mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-25 22:30:51 +08:00
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)
This commit is contained in:
parent
aa9a2c8429
commit
267e856494
37
.readthedocs.yaml
Normal file
37
.readthedocs.yaml
Normal file
@ -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
|
@ -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)
|
||||
|
||||
|
20
doc/create_page_list.sh
Executable file
20
doc/create_page_list.sh
Executable file
@ -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
|
Loading…
x
Reference in New Issue
Block a user