From caed01aad345ebae5f7538276f110e57e77f3c95 Mon Sep 17 00:00:00 2001 From: "E. Scott Daniels" Date: Fri, 12 Jun 2020 13:47:13 -0400 Subject: [PATCH] Correct release notes in RTD index The title in the index was incorrect. The release notes are now generated from the CHANGES log. Issue-ID: RIC-148 Signed-off-by: E. Scott Daniels Change-Id: Id648e7e9c9c3aed4f4e0e10e127f5bdb89016b47 --- doc/src/lib/rst.im | 31 ++++++++++--- doc/src/rtd/Makefile | 76 +++++++++++++++++++++++++++++++ doc/src/rtd/gen_rel_notes.sh | 63 ++++++++++++++++++++++++++ doc/src/rtd/rel-notes.rst | 31 +++++++++++++ doc/src/rtd/rel-notes.xfm | 25 +++++++++++ doc/src/rtd/setup.im | 103 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 4 +- docs/rel-notes.rst | 35 +++++++++++---- 8 files changed, 351 insertions(+), 17 deletions(-) create mode 100644 doc/src/rtd/Makefile create mode 100755 doc/src/rtd/gen_rel_notes.sh create mode 100644 doc/src/rtd/rel-notes.rst create mode 100644 doc/src/rtd/rel-notes.xfm create mode 100644 doc/src/rtd/setup.im diff --git a/doc/src/lib/rst.im b/doc/src/lib/rst.im index f20165e..e63a901 100644 --- a/doc/src/lib/rst.im +++ b/doc/src/lib/rst.im @@ -42,17 +42,34 @@ .dv many_equals ============================================================================================ .dv many_dashes -------------------------------------------------------------------------------------------- .dv many_tildas ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .dv h1 .sp 1 $1 .br &many_equals .sp 1 - .dv h2 .sp 1 $1 .br &many_dashes .sp 1 - .dv h3 .sp 1 $1 .br &many_tildas .sp 1 + + .gv semver + .if &_major 1 > + .** tfm version 2.0.0+ supports header annotation for rst + .dh 1 a==after s=2,1 i=0 m=0 + .dh 2 a=-after s=2,1 i=0 m=0 + .dh 3 a=~after s=2,0 i=0 m=0 + + .dv h1 .h1 $1 + .dv h2 .h2 $1 + .dv h3 .h2 $1 + .ei + .dv __alert ### WARNING ### rst.im detects an old(er) version of tfm some formatting might not be right + .sv __alert + + .dh 1 s=2,1 i=0 m=0 + .dh 2 s=1.1 i=0 m=0 + .dh 3 s=1,0 i=0 m=0 + + .dv h1 .sp 1 $1 .br &many_equals .sp 1 + .dv h2 .sp 1 $1 .br &many_dashes .sp 1 + .dv h3 .sp 1 $1 .br &many_tildas .sp 1 + .fi + .dv h4 **$1** .** bloody rst won't allow breaks in a bullet list so we have to allow the column to go wide. .dv cd 1 180i m=0i - .dv h4 **$1** - .** .dv h1 === $1 .br === .sp 1 - .** .dv h2 === $1 .br === .sp 1 - .** .dv h3 === $1 .br === .sp 1 .dv fig .dv set_font_cw diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile new file mode 100644 index 0000000..5a767df --- /dev/null +++ b/doc/src/rtd/Makefile @@ -0,0 +1,76 @@ +#================================================================================== +# Copyright (c) 2020 Nokia +# Copyright (c) 2020 AT&T Intellectual Property. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#================================================================================== + +# this uses {X}fm which can be cloned from: https://gitlab.com/rouxware/xfm + +docs = rel-notes +src = rel-notes.xfm +imbed_src = +desired_out = rst + +# use care: the output type is used to source the macros based on the type +# of output being rendered. +# Two pass builds allow for table of contents gen/insert, forward var +# references etc. +# +%.ps: %.xfm + OUTPUT_TYPE=generic_ps XFM_PASS=1 pfm $< /dev/null + OUTPUT_TYPE=generic_ps XFM_PASS=2 pfm $< $@ + +%.md: %.xfm + OUTPUT_TYPE=markdown XFM_PASS=1 tfm $< /dev/null + OUTPUT_TYPE=markdown XFM_PASS=2 tfm $< | sed 's/^ //' >$@ + +%.rst: %.xfm + OUTPUT_TYPE=rst XFM_PASS=1 tfm $< /dev/null + GEN_TITLE=1 OUTPUT_TYPE=rst XFM_PASS=2 tfm $< | sed 's/^ //' >$@ + +%.txt: %.xfm + OUTPUT_TYPE=txt XFM_PASS=1 tfm $< /dev/null + OUTPUT_TYPE=txt XFM_PASS=2 tfm $< $@ + +# ----------------------------------------------------------------------------------- + +# build and push all .rst files into scraper directory +all: $(docs:%=%.rst) + cp *.rst ../../../docs/ + +rel-notes.xfm: always + gen_rel_notes.sh >rel-notes.xfm + +rel-notes.rst: rel-notes.xfm $(imbed_src) + +# we force the .rst docs to always be out of date so that we don't have to +# jump hoops to ensure that they build for make publish. (See hack rule +# at the end of the file.) +# +$(docs:%=%.rst): always + +publish: user_guide.rst + cp *.rst ../../../docs/ + +# intermeidate junk that might straggle +clean: + rm -fr *.bcnfile *.ca *.ecnfile *.sp + +# Destroy anything that can be built +nuke: clean + rm -fr *.md *.ps *.pdf *.txt *.rst *.toc + +# make hack to force a rule to always be out of date +always: + diff --git a/doc/src/rtd/gen_rel_notes.sh b/doc/src/rtd/gen_rel_notes.sh new file mode 100755 index 0000000..eb3b99b --- /dev/null +++ b/doc/src/rtd/gen_rel_notes.sh @@ -0,0 +1,63 @@ +# vim: ts=4 noet sw=4: +#================================================================================== +# Copyright (c) 2019-2020 Nokia +# Copyright (c) 2018-2020 AT&T Intellectual Property. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#================================================================================== + +# Mnemonic: gen_rel_notes.sh +# Abstract: This script looks for CHANGES*.txt files at the top level +# and builds one {X}fm source file from which the release notes +# RTD file is created. + +cat <= 2019 { + print_raw = 1 # safe to print blank lines + printf( "&h2(%s)\n", $0 ) + next + } + + print_raw { print } + ' $x +done diff --git a/doc/src/rtd/rel-notes.rst b/doc/src/rtd/rel-notes.rst new file mode 100644 index 0000000..d622981 --- /dev/null +++ b/doc/src/rtd/rel-notes.rst @@ -0,0 +1,31 @@ +============================================================================================ +Release Notes +============================================================================================ + + +C++ Framework Release Notes +=========================== + +The following is a list of release highlights for the C++ +xAPP Framework. + + +Bronze Release +============== + + + +2020 April 28; version 1.0.0 +---------------------------- + +Bump version to force package build (old CI version added +incorrect install prefix). Bump to 1.0.0 for release. + + + +2020 March 27; version 0.1.2 +---------------------------- + +Changes identified by sonar (missing copy/move builders) +rmr_dump example programme Improvements to code for better +test coverage diff --git a/doc/src/rtd/rel-notes.xfm b/doc/src/rtd/rel-notes.xfm new file mode 100644 index 0000000..bdc1521 --- /dev/null +++ b/doc/src/rtd/rel-notes.xfm @@ -0,0 +1,25 @@ + +.** ------------------------------------------------------------------------ +.** CAUTION: This .xfm file is automatically generated by fmt_changes.ksh +.** do NOT edit. Use 'make rel-notes.xfm' to regenerate. +.** ------------------------------------------------------------------------ + +.dv GEN_TITLE 1 +.dv doc_title Release Notes + +.im setup.im +.dh 1 u=off + +&h1(C++ Framework Release Notes) +The following is a list of release highlights for the C++ xAPP Framework. + +&h1(Bronze Release) +&h2(2020 April 28; version 1.0.0) + Bump version to force package build (old CI version added + incorrect install prefix). Bump to 1.0.0 for release. +&space + +&h2(2020 March 27; version 0.1.2) + Changes identified by sonar (missing copy/move builders) + rmr_dump example programme + Improvements to code for better test coverage diff --git a/doc/src/rtd/setup.im b/doc/src/rtd/setup.im new file mode 100644 index 0000000..b05e487 --- /dev/null +++ b/doc/src/rtd/setup.im @@ -0,0 +1,103 @@ +.** vim: ts=4 sw=4 noet: +.if false +================================================================================== + Copyright (c) 2019-2020 Nokia + Copyright (c) 2018-2020 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi + +.if false + Mnemonic: setup.im + Abstract: Look at environment variables and pull in the correct setup prep + imbed file based on the desired output type (when running tfm). + Obviously, when running pfm we are always generating postscirpt + so this isn't really doing much. + Date: 6 November 2019 +.fi + +.if ! _setup_im + +.** allow environment LIB to override +.gv e LIB lib +.if ! lib + .dv lib ../lib +.fi + +.hn off + +.** CAUTION: xfm comparisons are reverse polish so "a b =" is true if a == b. +.if pfm + .dv ot postscript + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_TYPE ot + .if "&ot" "txt" = + .im &{lib}/txt.im + .fi + .if "&ot" "rst" = + .im &{lib}/rst.im + .fi + .if "&ot" "markdown" = + .im &{lib}/markdown.im + .fi + .if "&ot" "troff" = + .im &{lib}/roff.im + .fi + .if "&ot" "html" = + .im &{lib}/html.im + .fi +.fi + +.** if we can set a license into the output, do it early +.cd 1 11i +&line_len(10i) +.im license.im +.cd 1 6.5i m=0 i=0 +&line_len( 6i) + +.if ! textsize + .dv textsize 10 +.fi +.if ! textfont + .dv textfont Helvetica +.fi + +.if doc_title + .im &{lib}/library/front_junk.im +.fi + +.dv _setup_im 1 +.fi + +.if "&ot" "rst" = + .** copyright into .rst because it supports internal comments + .im license.im + + &many_equals .br + &doc_title + &many_equals .br + .if doc_subtitle + &many_dashes .br + &doc_subtitle .br + &many_dashes .br + .fi +.ei + ¢er_start + &doc_title .br + .if doc_subtitle + &doc_subtitle .br + .fi +.fi + diff --git a/docs/index.rst b/docs/index.rst index 37eb834..d4fc51f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,12 +14,14 @@ RIC xAPP C++ Framework .. toctree:: :maxdepth: 1 :caption: Documents: + :titlesonly: user-guide.rst .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Misc: + :titlesonly: rel-notes.rst diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst index 2bb881c..d622981 100644 --- a/docs/rel-notes.rst +++ b/docs/rel-notes.rst @@ -1,14 +1,31 @@ +============================================================================================ +Release Notes +============================================================================================ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. CAUTION: this document is generated from source in doc/src/rtd. -.. To make changes edit the source and recompile the document. -.. Do NOT make changes directly to .rst or .md files. +C++ Framework Release Notes +=========================== -RIC xAPP C++ Framework -====================== +The following is a list of release highlights for the C++ +xAPP Framework. -2020 April 22 Version 1.0.0 - Initial release +Bronze Release +============== + + + +2020 April 28; version 1.0.0 +---------------------------- + +Bump version to force package build (old CI version added +incorrect install prefix). Bump to 1.0.0 for release. + + + +2020 March 27; version 0.1.2 +---------------------------- + +Changes identified by sonar (missing copy/move builders) +rmr_dump example programme Improvements to code for better +test coverage -- 2.16.6