Proxmox/proxmox-backup
5
0
Fork 0
mirror of git://git.proxmox.com/git/proxmox-backup.git synced 2025-01-03 01:18:02 +03:00
Code Releases Activity
d430b05ec3
proxmox-backup/docs/Makefile
Thomas Lamprecht e5f2903981 docs: make sphinx ignore the environment cache to avoid missing synopsis 
Pass the `-E` option to, quoting it's man-page, "don't use a saved
environment (the structure caching all cross-references, but rebuild
it completely."

As with reusing the environment one gets some empty results for
synopsis stuff depending on build order, for example the synopsis in
the command-syntax appendix HTML output is empty while the same
synopsis used for the dedicated HTML page is complete.

By making the build-log more verbose I caught the attention of some
emitted 'env-purge-doc' events from sphinx; while this itself might be
harmless (I didn't followed the rat tail to its end), it made me a bit
suspicious about caching and wrong/missing invalidation.

With ignoring the environment this is fixed, a diffoscope comparison
shows that not only the command-syntax page, but many others have the
various synposis content added again. There are solely added lines, no
removed nor changed, so it seems fine to enabled that option without
an in-depth sphinx review.

Note, I first suspected the use of a separate "doctree pickles" cache
directory (`-d` option) and is used for all output types besides the
man-pages one, which uses the default .doctree directory.
But changing the man-page target to also use the custom doctree cache
had no effect on the build-result whatsoever (compared with
diffoscope).

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2024-11-27 19:37:46 +01:00

202 lines
6.2 KiB
Makefile
Raw Blame History

include ../defines.mk
GENERATED_SYNOPSIS := \
config/acl/roles.rst \
config/datastore/config.rst \
config/domains/config.rst \
config/media-pool/config.rst \
config/notifications-priv/config.rst \
config/notifications/config.rst \
config/remote/config.rst \
config/sync/config.rst \
config/tape-job/config.rst \
config/tape/config.rst \
config/user/config.rst \
config/verification/config.rst \
pmt/synopsis.rst \
pmtx/synopsis.rst \
proxmox-backup-client/catalog-shell-synopsis.rst \
proxmox-backup-client/synopsis.rst \
proxmox-backup-debug/synopsis.rst \
proxmox-backup-manager/synopsis.rst \
proxmox-file-restore/synopsis.rst \
proxmox-tape/synopsis.rst \
pxar/synopsis.rst \
MAN1_PAGES := \
pbs2to3.1 \
pmt.1 \
pmtx.1 \
proxmox-backup-client.1 \
proxmox-backup-debug.1 \
proxmox-backup-manager.1 \
proxmox-backup-proxy.1 \
proxmox-file-restore.1 \
proxmox-tape.1 \
pxar.1 \
# FIXME: prefix all man pages that are not directly relating to an existing executable with
# `proxmox-backup.`, like the newer added proxmox-backup.node.cfg but add backwards compatible
# symlinks, e.g. with a "5pbs" man page "suffix section".
MAN5_PAGES := \
acl.cfg.5 \
datastore.cfg.5 \
domains.cfg.5 \
media-pool.cfg.5 \
proxmox-backup.node.cfg.5 \
notifications-priv.cfg.5 \
notifications.cfg.5 \
remote.cfg.5 \
sync.cfg.5 \
tape-job.cfg.5 \
tape.cfg.5 \
user.cfg.5 \
verification.cfg.5 \
PRUNE_SIMULATOR_FILES := \
prune-simulator/index.html \
prune-simulator/clear-trigger.png \
prune-simulator/documentation.html \
prune-simulator/prune-simulator.js \
PRUNE_SIMULATOR_JS_SOURCE := \
/usr/share/javascript/proxmox-widget-toolkit-dev/Toolkit.js \
prune-simulator/prune-simulator_source.js
LTO_BARCODE_JS_SOURCE := \
/usr/share/javascript/proxmox-widget-toolkit-dev/Toolkit.js \
lto-barcode/code39.js \
lto-barcode/prefix-field.js \
lto-barcode/label-style.js \
lto-barcode/tape-type.js \
lto-barcode/paper-size.js \
lto-barcode/page-layout.js \
lto-barcode/page-calibration.js \
lto-barcode/label-list.js \
lto-barcode/label-setup.js \
lto-barcode/lto-barcode.js
LTO_BARCODE_FILES := \
lto-barcode/index.html \
lto-barcode/lto-barcode-generator.js
API_VIEWER_SOURCES= \
api-viewer/index.html \
api-viewer/apidoc.js
API_VIEWER_FILES := \
api-viewer/apidata.js \
/usr/share/javascript/proxmox-widget-toolkit-dev/APIViewer.js \
# Sphinx documentation setup
SPHINXOPTS = -E
SPHINXBUILD = sphinx-build
BUILDDIR = output
ifeq ($(BUILD_MODE), release)
COMPILEDIR := ../target/$(DEB_HOST_RUST_TYPE)/release
SPHINXOPTS += -t release
else
COMPILEDIR := ../target/$(DEB_HOST_RUST_TYPE)/debug
SPHINXOPTS += -t devbuild
endif
# Sphinx internal variables.
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
all: ${MAN1_PAGES} ${MAN5_PAGES}
config/%/config.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen $*.cfg >$@
config/acl/roles.rst: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen "config::acl::Role" >$@
%/synopsis.rst: ${COMPILEDIR}/%
$< printdoc > $@
proxmox-backup-client/catalog-shell-synopsis.rst: ${COMPILEDIR}/dump-catalog-shell-cli
${COMPILEDIR}/dump-catalog-shell-cli > proxmox-backup-client/catalog-shell-synopsis.rst
${MAN1_PAGES} ${MAN5_PAGES}: man-pages
.PHONY: man-pages
man-pages: ${GENERATED_SYNOPSIS}
${SPHINXBUILD} ${SPHINXOPTS} -b man ./ ${BUILDDIR}/man
.PHONY: onlinehelpinfo
onlinehelpinfo:
@echo "Generating OnlineHelpInfo.js..."
$(SPHINXBUILD) -b proxmox-scanrefs -Q $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
@echo "Build finished. OnlineHelpInfo.js is in $(BUILDDIR)/scanrefs."
api-viewer/apidata.js: ${COMPILEDIR}/docgen
${COMPILEDIR}/docgen apidata.js >$@
api-viewer/apidoc.js: ${API_VIEWER_FILES}
cat ${API_VIEWER_FILES} >$@.tmp
mv $@.tmp $@
prune-simulator/prune-simulator.js: ${PRUNE_SIMULATOR_JS_SOURCE}
cat ${PRUNE_SIMULATOR_JS_SOURCE} >$@.tmp
mv $@.tmp $@
lto-barcode/lto-barcode-generator.js: ${LTO_BARCODE_JS_SOURCE}
cat ${LTO_BARCODE_JS_SOURCE} >$@.tmp
mv $@.tmp $@
.PHONY: html
html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg _static/custom.css conf.py ${PRUNE_SIMULATOR_FILES} ${LTO_BARCODE_FILES} ${API_VIEWER_SOURCES}
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
install -m 0644 _static/custom.js _static/custom.css images/proxmox-logo.svg $(BUILDDIR)/html/_static/
install -dm 0755 $(BUILDDIR)/html/prune-simulator
install -m 0644 ${PRUNE_SIMULATOR_FILES} $(BUILDDIR)/html/prune-simulator
install -dm 0755 $(BUILDDIR)/html/lto-barcode
install -m 0644 ${LTO_BARCODE_FILES} $(BUILDDIR)/html/lto-barcode
install -dm 0755 $(BUILDDIR)/html/api-viewer
install -m 0644 ${API_VIEWER_SOURCES} $(BUILDDIR)/html/api-viewer
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: latexpdf
latexpdf: ${GENERATED_SYNOPSIS}
@echo "Requires python3-sphinx, texlive-xetex, xindy and texlive-fonts-extra"
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through xelatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: epub3
epub3: ${GENERATED_SYNOPSIS}
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
@echo
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
clean:
rm -r -f *~ *.1 ${BUILDDIR} ${GENERATED_SYNOPSIS} api-viewer/apidata.js
rm -f api-viewer/apidoc.js lto-barcode/lto-barcode-generator.js prune-simulator/prune-simulator.js
install_manual_pages: man-pages
install -dm755 $(DESTDIR)$(MAN1DIR)
for i in ${MAN1_PAGES}; do install -m755 ${BUILDDIR}/man/$$i $(DESTDIR)$(MAN1DIR)/ ; done
install -dm755 $(DESTDIR)$(MAN5DIR)
for i in ${MAN5_PAGES}; do install -m755 ${BUILDDIR}/man/$$i $(DESTDIR)$(MAN5DIR)/ ; done
install_html: html
install -dm755 $(DESTDIR)$(DOCDIR)
rsync -a ${BUILDDIR}/html $(DESTDIR)$(DOCDIR)
install_pdf: latexpdf
install -dm755 $(DESTDIR)$(DOCDIR)
install -m 0644 output/latex/ProxmoxBackup.pdf $(DESTDIR)$(DOCDIR)/proxmox-backup.pdf
ifneq ($(filter nodoc,$(DEB_BUILD_PROFILES)),)
install: install_manual_pages
else
install: install_manual_pages install_html install_pdf
endif
View Git Blame Copy Permalink