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
This commit is contained in:
Vadim Yanitskiy 2020-10-29 16:44:46 +07:00 committed by laforge
parent 744e44eaa1
commit 3fb4d31ecb
6 changed files with 70 additions and 1413 deletions

3
.gitignore vendored
View File

@ -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

View File

@ -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 \

View File

@ -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

View File

@ -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 '/^<vtydoc/,$$!d' "$@.gen"
# b) Merge the result of a) with global and local additions
$(OSMO_GSM_MANUALS_DIR)/build/vty_reference_combine.sh \
$(realpath $(OSMO_GSM_MANUALS_DIR)/merge_doc.xsl) "$@.gen" \
$(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \
$(srcdir)/vty/*additions*.xml > "$@.merged"
# c) Convert the result of b) into a valid docbook
xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl "$@.merged" > $@

View File

@ -6,7 +6,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
"http://docbook.org/xml/5.0/dtd/docbook.dtd" [
<!ENTITY chapter-vty SYSTEM "./common/chapters/vty.xml" >
<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
<!ENTITY sections-vty SYSTEM "@@GENERATED@@" >
]>
<book>
@ -18,12 +18,19 @@
<authorinitials>pe</authorinitials>
<revremark>Initial</revremark>
</revision>
<revision>
<revnumber>v2</revnumber>
<date>@@REV_DATE@@</date>
<authorinitials>s.f.m.c.</authorinitials>
<revremark>Automatic build (@@REV_NUMBER@@)</revremark>
</revision>
</revhistory>
<title>OsmoTRX VTY Reference</title>
<subtitle>@@VARIANT@@</subtitle>
<copyright>
<year>2018</year>
<year>@@CR_YEAR@@</year>
</copyright>
<legalnotice>

File diff suppressed because it is too large Load Diff