diff --git a/doc/Makefile.am b/doc/Makefile.am index a6a2f35363..ad46812f2d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,153 +1,150 @@ # # Copyright 2003-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # include $(top_srcdir)/mk/common.mk -# Define release-related variables +# Define release- and upload-related variables include $(top_srcdir)/mk/release.mk +include $(top_srcdir)/mk/uploads.mk # What formats to use for book uploads (i.e. "make www"; # use BOOK_FORMATS in sphinx subdirectory to change local builds) BOOK_FORMATS ?= html \ singlehtml \ pdf \ epub # SNMP MIB mibdir = $(datadir)/snmp/mibs dist_mib_DATA = PCMK-MIB.txt noinst_SCRIPTS = abi-check SUBDIRS = sphinx EXTRA_DIST = clusterlabs-logo-55x55.png -# toplevel rsync destination for www targets (without trailing slash) -RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html - -# recursive, preserve symlinks, preserve permissions, verbose, compress, -# don't cross filesystems, sparse, show progress -RSYNC_OPTS = -rlpvzxS --progress - if IS_ASCIIDOC ASCIIDOC_HTML_ARGS = --unsafe --backend=xhtml11 ASCIIDOC_DBOOK_ARGS = -b docbook -d book else ASCIIDOC_HTML_ARGS = --backend=html5 ASCIIDOC_DBOOK_ARGS = -b docbook45 -d book endif %.html: %.txt $(AM_V_GEN)$(ASCIIDOC_CONV) $(ASCIIDOC_HTML_ARGS) --out-file=$@ $< $(PCMK_quiet) # For Makefile debugging .PHONY: vars vars: @echo LAST_RELEASE=\'$(LAST_RELEASE)\' @echo TAG=\'$(TAG)\' + @echo RSYNC_DEST=\'$(RSYNC_DEST)\' + @echo RSYNC_PACKAGE_DEST=\'$(RSYNC_PACKAGE_DEST)\' # Annotated source code as HTML # Cleaning first ensures we don't index unrelated stuff like RPM sources .PHONY: global global: $(MAKE) $(AM_MAKEFLAGS) -C .. clean-generic $(MAKE) $(AM_MAKEFLAGS) -C ../rpm rpm-clean cd .. && gtags -q && htags -sanhIT doc .PHONY: global-upload global-upload: global - rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_DEST)/projects/$(PACKAGE)/global/$(TAG)/" + rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_PACKAGE_DEST)/global/$(TAG)/" .PHONY: global-clean global-clean: -rm -rf HTML # Man pages as HTML MANPAGE_DIRS = ../agents ../daemons ../tools %.8.html: %.8 groff -mandoc `man -w ./$<` -T html > $@ %.7.html: %.7 groff -mandoc `man -w ./$<` -T html > $@ .PHONY: manhtml manhtml: $(MAKE) $(AM_MAKEFLAGS) -C .. all find $(MANPAGE_DIRS) -name "[a-z]*.[78]" \ -exec $(MAKE) $(AM_MAKEFLAGS) \{\}.html \; .PHONY: manhtml-upload manhtml-upload: manhtml find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec \ - rsync $(RSYNC_OPTS) \{\} "$(RSYNC_DEST)/projects/$(PACKAGE)/man/" \; + rsync $(RSYNC_OPTS) \{\} "$(RSYNC_PACKAGE_DEST)/man/" \; .PHONY: manhtml-clean manhtml-clean: -find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec rm \{\} \; # API documentation as HTML .PHONY: doxygen doxygen: Doxyfile doxygen Doxyfile .PHONY: doxygen-upload doxygen-upload: doxygen - rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_DEST)/projects/$(PACKAGE)/doxygen/$(TAG)/" + rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_PACKAGE_DEST)/doxygen/$(TAG)/" .PHONY: doxygen-clean doxygen-clean: -rm -rf api # ABI compatibility report as HTML .PHONY: abi abi: abi-check ./abi-check $(PACKAGE) $(LAST_RELEASE) $(TAG) .PHONY: abi-www abi-www: - export RSYNC_DEST=$(RSYNC_DEST); ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG) + export RSYNC_PACKAGE_DEST=$(RSYNC_PACKAGE_DEST); \ + ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG) .PHONY: abi-clean abi-clean: -rm -rf abi_dumps compat_reports # The main documentation books (which are actually in the sphinx subdirectory) .PHONY: books-upload books-upload: $(MAKE) $(AM_MAKEFLAGS) -C sphinx clean $(MAKE) $(AM_MAKEFLAGS) -C sphinx \ RSYNC_DEST="$(RSYNC_DEST)" \ BOOK_FORMATS="$(BOOK_FORMATS)" \ books-upload # All online documentation (except ABI compatibility, which is run separately) .PHONY: www www: clean-local manhtml-upload global-upload doxygen-upload books-upload .PHONY: clean-local clean-local: global-clean manhtml-clean doxygen-clean abi-clean # "make check" will cause "make all" to be run, which means docs will get built # as a part of running tests if they haven't already. That seems unnecessary, so # override the default check-recursive rule with this one that just returns. If # we ever need to add tests to this directory, this rule will have to come out. .PHONY: check-recursive check-recursive: @true diff --git a/doc/abi-check.in b/doc/abi-check.in index 6b6a8d3d78..754e4d39c1 100755 --- a/doc/abi-check.in +++ b/doc/abi-check.in @@ -1,164 +1,164 @@ #!@BASH_PATH@ # -# Copyright 2011-2023 the Pacemaker project contributors +# Copyright 2011-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # # # abi-check [-u] [...] # # Build ABI dumps for all listed versions. If exactly two are given, # build an ABI compatibility report for them, and if -u is given, # upload it to the website. # -# Top-level rsync destination for www targets (without trailing slash) -: ${RSYNC_DEST:=root@www.clusterlabs.org:/var/www/html} +# Top-level rsync destination for package's file uploads (without trailing slash) +: ${RSYNC_PACKAGE_DEST:=sites.clusterlabs.org:/var/www/html/projects/$(PACKAGE)} # If the argument is of form x.y.z, print Pacemaker-x.y.z, # otherwise print the argument (presumably a commit ID) directly tag() { if [[ "$1" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3} ]]; then echo "Pacemaker-$1" else echo "$1" fi } sed_in_place() { cp -p "$1" "$1.$$" sed -e "$2" "$1" > "$1.$$" mv "$1.$$" "$1" } # Strip anything up to and including a dash from the argument version() { echo "$1" | sed s:.*-:: } # Create configuration file for ABI dumper abi_config() { PACKAGE="$1" VERSION="$2" BUILD_ROOT="$3" DESC="$4" # Create header DESC="$BUILD_ROOT/$VERSION.xml" cat < "$DESC" $VERSION $BUILD_ROOT/root/usr/include/$PACKAGE/crm EOF # Build checkout, installing into subdirectory ( cd "$BUILD_ROOT" && ./autogen.sh && ./configure --disable-fatal-warnings ) make -C "$BUILD_ROOT" V=0 DESTDIR="${BUILD_ROOT}/root" install if [ $? -ne 0 ]; then echo "Build for $TAG failed. Repair, populate and re-run: " echo " abi-compliance-checker -l $PACKAGE -dump_abi $DESC" echo "" echo "To find libraries after building:" echo " find $BUILD_ROOT/root -name "*.so" -print" exit 1 fi # Add library names to configuration file find $BUILD_ROOT/root -name "*.so" -print >> $DESC # Add footer cat <> "$DESC" EOF } # Dump the ABI for a particular version extract_one() { TAG="$1" VERSION="$2" # If dump already exists, remove it if dumping HEAD (which changes), # otherwise use it (a dump for a particular commit stays the same). TARBALL="abi_dumps/$PACKAGE/${PACKAGE}_$VERSION.abi.tar.gz" if [ "$VERSION" = HEAD ]; then rm -rf "$TARBALL" elif [ -f "$TARBALL" ]; then return fi echo "Building ABI dump for $*" # Get a clean checkout at the desired commit BUILD_ROOT=".ABI-build" rm -rf "$BUILD_ROOT" ( cd .. ; git archive --prefix "doc/$BUILD_ROOT/" "$TAG" | tar xv ) if [ $? -ne 0 ]; then exit fi # Remove "doc" from SUBDIRS in Makefile (but why?) BUILD_ROOT="$(pwd)/$BUILD_ROOT" sed_in_place "$BUILD_ROOT/Makefile.am" 's: doc::' # Run ABI dump abi_config "$PACKAGE" "$VERSION" "$BUILD_ROOT" "$DESC" abi-compliance-checker -l "$PACKAGE" -dump_abi "$DESC" \ -dump-path "abi_dumps/${PACKAGE}/${PACKAGE}_${VERSION}.abi.tar.gz" # Clean up rm -rf "$BUILD_ROOT" } extract_all() { for arg in $*; do T=$(tag "$arg") V=$(version "$T") extract_one "$T" "$V" done } die() { echo "$@" 1>&2 exit 1 } which git 2>/dev/null || die "abi-check: git must be installed" git rev-parse --git-dir >/dev/null 2>/dev/null \ || die "abi-check: must be run from git checkout" UPLOAD=0 if [ "$1" = "-u" ]; then UPLOAD=1; shift fi PACKAGE="$1"; shift extract_all "$@" if [ $# -eq 2 ]; then V1=$(version "$1") V2=$(version "$2") abi-compliance-checker -l ${PACKAGE} \ -d1 abi_dumps/${PACKAGE}/${PACKAGE}_${V1}.abi.tar.gz \ -d2 abi_dumps/${PACKAGE}/${PACKAGE}_${V2}.abi.tar.gz if [ $? -ne 0 ]; then echo "WARNING: compliance checker exited $?" fi COMPAT_REPORT="compat_reports/${PACKAGE}/${V1}_to_${V2}" if [ $UPLOAD -eq 1 ] && [ -d "$COMPAT_REPORT" ]; then - rsync -azxlSD --progress "$COMPAT_REPORT" "${RSYNC_DEST}/${PACKAGE}/abi/" + rsync -azxlSD --progress "$COMPAT_REPORT" "${RSYNC_PACKAGE_DEST}/abi/" fi fi diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am index 29421c72f6..2ba43ea9a7 100644 --- a/doc/sphinx/Makefile.am +++ b/doc/sphinx/Makefile.am @@ -1,233 +1,228 @@ # # Copyright 2003-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # include $(top_srcdir)/mk/common.mk -# Define release-related variables +# Define release- and upload-related variables include $(top_srcdir)/mk/release.mk +include $(top_srcdir)/mk/uploads.mk # Things you might want to override on the command line # Books to generate BOOKS ?= Clusters_from_Scratch \ Pacemaker_Administration \ Pacemaker_Development \ Pacemaker_Explained \ Pacemaker_Python_API \ Pacemaker_Remote # Output formats to generate. Possible values: # html (multiple HTML files) # dirhtml (HTML files named index.html in multiple directories) # singlehtml (a single large HTML file) # text # pdf # epub # latex # linkcheck (not actually a format; check validity of external links) # # The results will end up in /_build/ BOOK_FORMATS ?= singlehtml # Set to "a4paper" or "letterpaper" if building latex format PAPER ?= letterpaper # Additional options for sphinx-build SPHINXFLAGS ?= -# toplevel rsync destination for www targets (without trailing slash) -RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html - # End of useful overrides # Example scheduler transition graphs # @TODO The original CIB XML for these is long lost. Ideally, we would recreate # something similar and keep those here instead of the DOTs (or use a couple of # scheduler regression test inputs instead), then regenerate the SVG # equivalents using crm_simulate and dot when making a release. DOTS = $(wildcard shared/images/*.dot) # Vector sources for generated PNGs (including SVG equivalents of DOTS, created # manually using dot) SVGS = $(wildcard shared/images/pcmk-*.svg) \ $(DOTS:%.dot=%.svg) # PNG images generated from SVGS # # These will not be accessible in a VPATH build, which will generate warnings # when building the documentation, but the make will still succeed. It is # nontrivial to get them working for VPATH builds and not worth the effort. PNGS_GENERATED = $(SVGS:%.svg=%.png) # Original PNG image sources PNGS_Clusters_from_Scratch = $(wildcard Clusters_from_Scratch/images/*.png) PNGS_Pacemaker_Explained = $(wildcard Pacemaker_Explained/images/*.png) PNGS_Pacemaker_Remote = $(wildcard Pacemaker_Remote/images/*.png) STATIC_FILES = $(wildcard _static/*.css) EXTRA_DIST = $(wildcard */*.rst) $(DOTS) $(SVGS) \ $(PNGS_Clusters_from_Scratch) \ $(PNGS_Pacemaker_Explained) \ $(PNGS_Pacemaker_Remote) \ $(wildcard Pacemaker_Python_API/_templates/*rst) \ $(STATIC_FILES) \ conf.py.in -# recursive, preserve symlinks/permissions/times, verbose, compress, -# don't cross filesystems, sparse, show progress -RSYNC_OPTS = -rlptvzxS --progress - PACKAGE_SERIES=$(shell echo "$(VERSION)" | awk -F. '{ print $$1"."$$2 }') -BOOK_RSYNC_DEST = $(RSYNC_DEST)/projects/$(PACKAGE)/doc/$(PACKAGE_SERIES) +BOOK_RSYNC_DEST = $(RSYNC_PACKAGE_DEST)/doc/$(PACKAGE_SERIES) BOOK = none DEPS_intro = shared/pacemaker-intro.rst \ $(PNGS_GENERATED) DEPS_Clusters_from_Scratch = $(DEPS_intro) \ $(PNGS_Clusters_from_Scratch) DEPS_Pacemaker_Administration = $(DEPS_intro) DEPS_Pacemaker_Development = DEPS_Pacemaker_Explained = $(DEPS_intro) \ $(PNGS_Pacemaker_Explained) DEPS_Pacemaker_Python_API = ../../python DEPS_Pacemaker_Remote = $(PNGS_Pacemaker_Remote) if BUILD_SPHINX_DOCS INKSCAPE_CMD = $(INKSCAPE) --export-dpi=90 -C # Pattern rule to generate PNGs from SVGs # (--export-png works with Inkscape <1.0, --export-filename with >=1.0; # create the destination directory in case this is a VPATH build) %.png: %.svg $(AM_V_at)-$(MKDIR_P) "$(shell dirname "$@")" $(AM_V_GEN) { \ $(INKSCAPE_CMD) --export-png="$@" "$<" 2>/dev/null \ || $(INKSCAPE_CMD) --export-filename="$@" "$<"; \ } $(PCMK_quiet) # Create a book's Sphinx configuration. # Create the book directory in case this is a VPATH build. $(BOOKS:%=%/conf.py): conf.py.in $(AM_V_at)-$(MKDIR_P) "$(@:%/conf.py=%)" $(AM_V_GEN)sed \ -e 's/%VERSION%/$(VERSION)/g' \ -e 's/%BOOK_ID%/$(@:%/conf.py=%)/g' \ -e 's/%BOOK_TITLE%/$(subst _, ,$(@:%/conf.py=%))/g' \ -e 's#%SRC_DIR%#$(abs_srcdir)#g' \ -e 's#%ABS_TOP_SRCDIR%#$(abs_top_srcdir)#g' \ -e 's#%CONFIGDIR%#@CONFIGDIR@#g' \ -e 's#%CRM_BLACKBOX_DIR%#@CRM_BLACKBOX_DIR@#g' \ -e 's#%CRM_CONFIG_DIR%#@CRM_CONFIG_DIR@#g' \ -e 's#%CRM_DAEMON_GROUP%#@CRM_DAEMON_GROUP@#g' \ -e 's#%CRM_DAEMON_USER%#@CRM_DAEMON_USER@#g' \ -e 's#%CRM_LOG_DIR%#@CRM_LOG_DIR@#g' \ -e 's#%CRM_SCHEMA_DIRECTORY%#@CRM_SCHEMA_DIRECTORY@#g' \ -e 's#%PACEMAKER_CONFIG_DIR%#@PACEMAKER_CONFIG_DIR@#g' \ -e 's#%PCMK_GNUTLS_PRIORITIES%#@PCMK_GNUTLS_PRIORITIES@#g' \ -e 's#%PCMK__REMOTE_SCHEMA_DIR%#@PCMK__REMOTE_SCHEMA_DIR@#g' \ $(<) > "$@" $(BOOK)/_build: $(STATIC_FILES) $(BOOK)/conf.py $(DEPS_$(BOOK)) $(wildcard $(srcdir)/$(BOOK)/*.rst) @echo 'Building "$(subst _, ,$(BOOK))" because of $?' $(PCMK_quiet) $(AM_V_at)rm -rf "$@" $(AM_V_BOOK)for format in $(BOOK_FORMATS); do \ echo -e "\n * Building $$format" $(PCMK_quiet); \ doctrees="doctrees"; \ real_format="$$format"; \ case "$$format" in \ pdf) real_format="latex" ;; \ gettext) doctrees="gettext-doctrees" ;; \ esac; \ $(SPHINX) -b "$$real_format" -d "$@/$$doctrees" \ -c "$(builddir)/$(BOOK)" \ -D latex_elements.papersize=$(PAPER) \ $(SPHINXFLAGS) \ "$(srcdir)/$(BOOK)" "$@/$$format" \ $(PCMK_quiet); \ if [ "$$format" = "pdf" ]; then \ $(MAKE) $(AM_MAKEFLAGS) -C "$@/$$format" \ all-pdf; \ fi; \ done endif build-$(PACKAGE_SERIES).txt: all $(AM_V_GEN)echo "Generated on `date --utc` from version $(TAG)" > "$@" .PHONY: books-upload books-upload: all build-$(PACKAGE_SERIES).txt if BUILD_SPHINX_DOCS @echo "Uploading $(PACKAGE_SERIES) documentation set" @for book in $(BOOKS); do \ echo " * $$book"; \ rsync $(RSYNC_OPTS) $(BOOK_FORMATS:%=$$book/_build/%) \ "$(BOOK_RSYNC_DEST)/$$book/"; \ done @rsync $(RSYNC_OPTS) "$(builddir)/build-$(PACKAGE_SERIES).txt" \ - "$(RSYNC_DEST)/projects/$(PACKAGE)/doc" + "$(RSYNC_PACKAGE_DEST)/doc" endif .PHONY: vars vars: @echo "BOOK_FORMATS='$(BOOK_FORMATS)'" @echo "PAPER='$(PAPER)'" @echo "SPHINXFLAGS='$(SPHINXFLAGS)'" @echo "RSYNC_DEST='$(RSYNC_DEST)'" + @echo "RSYNC_PACKAGE_DEST='$(RSYNC_PACKAGE_DEST)'" @echo "VERSION='$(VERSION)'" @echo "PACKAGE_SERIES='$(PACKAGE_SERIES)'" .PHONY: all-local all-local: if BUILD_SPHINX_DOCS @for book in $(BOOKS); do \ $(MAKE) $(AM_MAKEFLAGS) BOOK=$$book \ PAPER="$(PAPER)" SPHINXFLAGS="$(SPHINXFLAGS)" \ BOOK_FORMATS="$(BOOK_FORMATS)" $$book/_build; \ done endif .PHONY: install-data-local install-data-local: all-local if BUILD_SPHINX_DOCS $(AM_V_at)for book in $(BOOKS); do \ for format in $(BOOK_FORMATS); do \ formatdir="$$book/_build/$$format"; \ for f in `find "$$formatdir" -print`; do \ dname="`echo $$f | sed s:_build/::`"; \ dloc="$(DESTDIR)/$(docdir)/$$dname"; \ if [ -d "$$f" ]; then \ $(INSTALL) -d -m 755 "$$dloc"; \ else \ $(INSTALL_DATA) "$$f" "$$dloc"; \ fi \ done; \ done; \ done endif .PHONY: uninstall-local uninstall-local: if BUILD_SPHINX_DOCS $(AM_V_at)for book in $(BOOKS); do \ rm -rf "$(DESTDIR)/$(docdir)/$$book"; \ done endif .PHONY: clean-local clean-local: $(AM_V_at)-rm -rf \ $(BOOKS:%="$(builddir)/%/_build") \ $(BOOKS:%="$(builddir)/%/conf.py") \ $(BOOKS:%="$(builddir)/%/generated") \ $(PNGS_GENERATED) diff --git a/mk/uploads.mk b/mk/uploads.mk new file mode 100644 index 0000000000..07808aec4f --- /dev/null +++ b/mk/uploads.mk @@ -0,0 +1,19 @@ +# +# Copyright 2024 the Pacemaker project contributors +# +# The version control history for this file may have further details. +# +# This source code is licensed under the GNU General Public License version 2 +# or later (GPLv2+) WITHOUT ANY WARRANTY. +# + +# Variables useful for uploading files to a server + +# toplevel rsync destination (without trailing slash) +RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html + +RSYNC_PACKAGE_DEST = $(RSYNC_DEST)/projects/$(PACKAGE) + +# recursive, preserve symlinks, preserve permissions, verbose, compress, +# don't cross filesystems, sparse, show progress +RSYNC_OPTS = -rlpvzxS --progress