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 <daniels@research.att.com>
Change-Id: Id648e7e9c9c3aed4f4e0e10e127f5bdb89016b47

diff --git a/doc/src/lib/rst.im b/doc/src/lib/rst.im
index f20165e..e63a901 100644 (file)
--- 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 (file)
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 (executable)
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 <<endKat
+
+.** ------------------------------------------------------------------------
+.** 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.
+
+endKat
+
+for x in ../../../CHANGES*
+do
+       awk '
+               /^#/ { next }           # ditch all comments
+
+               # tag project releases by matching release tag associated
+               /1\.0\.0$/  { printf( "&h1(Bronze Release)\n" ) }
+
+               print_raw && /^$/ {                             # include blank lines after first real stuff
+                       printf( "&space\n\n" );
+                       next
+               }
+
+               $1+0 >= 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 (file)
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 (file)
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 (file)
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
+    &center_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 (file)
--- 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 (file)
--- 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