From 3fb4d31ecb1dc8c2038e4e17a7563e35795d663a Mon Sep 17 00:00:00 2001 From: Vadim Yanitskiy Date: Thu, 29 Oct 2020 16:44:46 +0700 Subject: [PATCH] doc/manuals: generate XML VTY reference at build-time Unfortunately, we cannot re-use the existing Makefile rules from: $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc because they do not allow to generate the list of $(DOCBOOKS) from a template, and require the project to store everything in separate folders with specific names. Also, those rules expect that the target PDFs contain only a single word in their names (for example, 'osmoapp-vty-reference', not 'osmo-app-vty-reference'), while in a project with multiple similarly named targets this would reduce readability (imagine 'osmotrxuhd-vty-reference'). Change-Id: I798ea3b7417b8ca3e9c7d50911158c5413526237 Depends: I6aac73d998c5937894233631e654a160d5623198 Related: SYS#4937, SYS#4910 --- .gitignore | 3 + Makefile.am | 5 +- doc/manuals/Makefile.am | 21 +- doc/manuals/vty/Makefile.vty-reference.inc | 37 + .../{ => vty}/osmotrx-vty-reference.xml | 11 +- doc/manuals/vty/trx_vty_reference.xml | 1406 ----------------- 6 files changed, 70 insertions(+), 1413 deletions(-) create mode 100644 doc/manuals/vty/Makefile.vty-reference.inc rename doc/manuals/{ => vty}/osmotrx-vty-reference.xml (70%) delete mode 100644 doc/manuals/vty/trx_vty_reference.xml diff --git a/.gitignore b/.gitignore index 4baa72a8..43fdfc2a 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,9 @@ doc/manuals/*.pdf doc/manuals/*__*.png doc/manuals/*.check doc/manuals/generated/ +doc/manuals/vty/osmotrx-*-vty-reference.xml +doc/manuals/vty/osmotrx-*-vty-reference.xml.inc.gen +doc/manuals/vty/osmotrx-*-vty-reference.xml.inc.merged doc/manuals/osmomsc-usermanual.xml doc/manuals/common doc/manuals/build diff --git a/Makefile.am b/Makefile.am index 01523414..6a3a955f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -28,13 +28,14 @@ AM_CXXFLAGS = -Wall -pthread # Order must be preserved SUBDIRS = \ - doc \ CommonLibs \ GSM \ Transceiver52M \ contrib \ tests \ - utils + utils \ + doc \ + $(NULL) EXTRA_DIST = \ LEGAL \ diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am index 7bf1f584..ed7353d4 100644 --- a/doc/manuals/Makefile.am +++ b/doc/manuals/Makefile.am @@ -1,6 +1,5 @@ EXTRA_DIST = osmotrx-usermanual.adoc \ osmotrx-usermanual-docinfo.xml \ - osmotrx-vty-reference.xml \ chapters \ vty @@ -9,8 +8,24 @@ if BUILD_MANUALS ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc - VTY_REFERENCE = osmotrx-vty-reference.xml - include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc + VARIANTS = $(NULL) + +if DEVICE_UHD + VARIANTS += uhd +endif +if DEVICE_USRP1 + VARIANTS += usrp1 +endif +if DEVICE_LMS + VARIANTS += lms +endif +if DEVICE_IPC + VARIANTS += ipc +endif + + # This is a significantly modified, multi-target adopted copy of + # $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc + include $(srcdir)/vty/Makefile.vty-reference.inc OSMO_REPOSITORY = osmo-trx include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc diff --git a/doc/manuals/vty/Makefile.vty-reference.inc b/doc/manuals/vty/Makefile.vty-reference.inc new file mode 100644 index 00000000..d86f638b --- /dev/null +++ b/doc/manuals/vty/Makefile.vty-reference.inc @@ -0,0 +1,37 @@ +DOCBOOKS = $(foreach v,$(VARIANTS),vty/osmotrx-$(v)-vty-reference.xml) +DOCBOOKS_DEPS = $(DOCBOOKS) $(addsuffix .inc,$(DOCBOOKS)) +INC_DIR = $(abspath $(builddir)/vty) + +include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.docbook.inc + +CLEAN_FILES += $(DOCBOOKS_DEPS) +CLEAN_FILES += $(addsuffix .inc.gen,$(DOCBOOKS)) +CLEAN_FILES += $(addsuffix .inc.merged,$(DOCBOOKS)) + +$(INC_DIR): + mkdir -p $@ + +vty/osmotrx-%-vty-reference.xml: $(top_builddir)/Transceiver52M/osmo-trx-% $(INC_DIR) + sed -e "s|@@GENERATED@@|$@.inc|" \ + -e "s|@@VARIANT@@|$(notdir $<)|" \ + -e "s|@@REV_NUMBER@@|$(VERSION)|" \ + -e "s|@@REV_DATE@@|$(shell date +"%dth %B %Y")|" \ + -e "s|@@CR_YEAR@@|$(shell date +"%Y")|" \ + $(srcdir)/vty/osmotrx-vty-reference.xml > $@ + +vty/osmotrx-%-vty-reference.xml.inc: $(top_builddir)/Transceiver52M/osmo-trx-% \ + $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ + $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \ + $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl \ + $(srcdir)/vty/*.xml $(INC_DIR) + # a) Invoke osmo-trx-% to generate the list of commands first + $< --vty-ref-mode default --vty-ref-xml > "$@.gen" + # ... filter garbage potentially printed by libraries to stdout + sed -i '/^ "$@.merged" + # c) Convert the result of b) into a valid docbook + xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl "$@.merged" > $@ diff --git a/doc/manuals/osmotrx-vty-reference.xml b/doc/manuals/vty/osmotrx-vty-reference.xml similarity index 70% rename from doc/manuals/osmotrx-vty-reference.xml rename to doc/manuals/vty/osmotrx-vty-reference.xml index 42919292..4d2a23d9 100644 --- a/doc/manuals/osmotrx-vty-reference.xml +++ b/doc/manuals/vty/osmotrx-vty-reference.xml @@ -6,7 +6,7 @@ - + ]> @@ -18,12 +18,19 @@ pe Initial + + v2 + @@REV_DATE@@ + s.f.m.c. + Automatic build (@@REV_NUMBER@@) + OsmoTRX VTY Reference + @@VARIANT@@ - 2018 + @@CR_YEAR@@ diff --git a/doc/manuals/vty/trx_vty_reference.xml b/doc/manuals/vty/trx_vty_reference.xml deleted file mode 100644 index ff44078e..00000000 --- a/doc/manuals/vty/trx_vty_reference.xml +++ /dev/null @@ -1,1406 +0,0 @@ - - - Common Commands - These commands are available on all VTY nodes. They are listed here only once, to unclutter the VTY reference. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - view - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - enable - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - config - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - config-log - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - config-stats - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - config-line - - - - - - - - - - - - - - - - - - - - - config-ctrl - - - - - - - - - config-trx - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - config-trx-chan - - - - - - - - - - - - - -