Add doc support and other CI related files
This change adds verious bits needed for CI and/or documentation
scraping as well as some README files.
The version in the CMake file was set to 0.1.0 in prep for activation
of CI jobs -- we want to be able to fiddle with those without actually
pushing a 1.x.x package to the repo. Once CI jobs are working we can
up the version to 1.0.0 to match the AP version.
Issue-ID: RIC-684
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: Iac2c24a8e8f1c01af74e20c0bce9cad1c6bf6702
diff --git a/.gitignore b/.gitignore
index c4d997b..0c9ff43 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
*-
attic/
.push_type
+.build/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..3797dc8
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,20 @@
+---
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+version: 2
+
+formats:
+ - htmlzip
+
+build:
+ image: latest
+
+python:
+ version: 3.7
+ install:
+ - requirements: docs/requirements-docs.txt
+
+sphinx:
+ configuration: docs/conf.py
diff --git a/CMakeLists.txt b/CMakeLists.txt
index de81724..9e6a1ff 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -31,8 +31,8 @@
# name (e.g. ORAN-WG3.E2AP-v01.00, would be 1.0). The patch version can be increased for
# small tweaks and possibly corrections (omissions/inclusions etc.) as is needed.
#
-set( major_version "1" )
-set( minor_version "0" )
+set( major_version "0" )
+set( minor_version "1" )
set( patch_level "0" )
set( install_root "${CMAKE_INSTALL_PREFIX}" )
diff --git a/CONTENTS b/CONTENTS
new file mode 100644
index 0000000..5d1ff39
--- /dev/null
+++ b/CONTENTS
@@ -0,0 +1,34 @@
+This directory contains files which may seem (and probably are)
+out of place in the root. Mostly these are CI files which should
+really be placed into a CI directory, but must exist here else
+the CI mechanics fall over. This is a list of these odd files.
+
+
+docs -- This directory contains generated documentation that is
+ scraped and placed on an external documentation site. The directory
+ name must be exactly "doc" and the CI/doc jobs fail if there
+ are files in the directory which are not referenced by the
+ index.
+
+rmr-version.yaml The CI vetting processes create environments
+ which include the RMR libraries. This file contains a single
+ definition of the desired RMR version to use in these
+ environments. There should be no need for RMR in any of
+ the evironments used to vet this code, so the version here
+ just needs to reference something available.
+
+tox.ini -- It is unclear exactly what this is for given that
+ there is no python code associated with this repo. The only
+ guess is that the document scraper/verification CI job is
+ a python application and requires this.
+
+.readthedocs.yaml -- Another doc CI configuration bit of goop.
+
+releases -- This is a directory which contains a single yaml file
+ used to indicate to the CI jobs which library should be moved
+ from the package cloud staging repo to the release repo. See
+ the README in that directory for more details.
+
+
+The rest of the files, like .git* should be well known to developers
+and thus are not explained here.
diff --git a/doc/src/lib/setup.im b/doc/src/lib/setup.im
new file mode 100644
index 0000000..0a41d38
--- /dev/null
+++ b/doc/src/lib/setup.im
@@ -0,0 +1,132 @@
+.if false
+==================================================================================
+ 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.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic: setup.im
+ Abstract: Provide general setup for all documents. It will include the
+ {X}fm common macro definitions (cmd) which provide the ability
+ to generate markdown, roff, and RST "source" from {X}fm source
+ while still allowing postscript to be generated.
+
+ Visit gitlab.com/rouxware/xfm for info on how to bulid
+ {X}fm if needed.
+
+ Date: 29 July 2019
+.fi
+
+
+.if ! _setup_im
+ .dv _setup_im 1
+
+ .** our imbeds live here
+ .dv lib ../lib
+
+ .** sane default for everything except rst
+ .dv col_width 6.5i
+ .dv textsize 10
+ .dv textfont Helvetica
+ .dv boldfont Helvetica-Bold
+ .hn off
+ .tm .75i
+
+ .** imbed output type specific macro file
+ .gv e OUTPUT_TYPE ot
+ .dv output_type &{ot!txt}
+
+
+ .** {X}fm package provided common macro definitions
+ .im cmd_master.im
+
+ .** because of the current RTD "template" we MUST force double spaceing
+ .** in definition lists else the bloody thing runs them all onto one line.
+ .** the following will do this and is harmless for other output types.
+ &force_diterm_breaks
+
+ .gv e XFM_PASS pass
+ .dv pass &{pass!1}
+
+
+ .** check that current version of {X}fm is greater/equal to our minimum req'd
+ .if ! [ "2.3.2" CVGE ]
+ .gv
+ .mg ### WARN ### this document source expects {X}fm version 2.3.2 or greater; found &{_major}.&{_minor}.&_patch
+ .fi
+
+ .gv e XFM_PATH xpath
+ .if ! xpath
+ .gv e TFM_PATH xpath
+ .if ! xpath
+ .mg ### WARNING ### XFM_PATH should be set to reference the shared imbed files; likely these are in /usr/local/share/xfm
+ .fi
+ .fi
+
+ .** forward variable reference support
+ .** define a 'subroutine' to add a variable and place it into the forward reference file
+ .** fref_sub.ca contains code to execute by the set_fref macor and fref.ca contains the
+ .** forward references to include during pass2. The macro set_ref will define the variable
+ .** passed as $1 (name) with the value passed as $2 and will add it to the fref.ca file.
+ .**
+ .ca shift start _fref_sub.ca
+ .** be careful... the next 'ca end' MUST be tab indented before {X} version 2.4.
+ .** with 2.4 and after it can be space indented
+
+ .ca expand extend _fref.ca
+ .dv &vname &vval
+ .ca end
+.ca end
+.** the previous 'ca end' MUST be in col 0
+ .dv export_var .dv vname $1 ^: .dv vval $2 ^: .dv $1 $2 ^: .im _fref_sub.ca
+ .dv export_fig .dv vname $1 ^: .gv fig .ev ^`.dv vval ^^&_fig ^: ^` .im _fref_sub.ca
+ .dv export_tab .dv vname $1 ^: .gv table .ev ^`.dv vval ^^&_table ^` ^: .im _fref_sub.ca
+ .dv export_pg .dv vname $1 ^: .gv page .ev ^`.dv vval ^^&_page ^` ^: .im _fref_sub.ca
+
+
+ .if &pass 2 =
+ .im _fref.ca
+ .ei
+ .** initialise the forward ref file
+ .ca start _fref.ca
+ .** forward reference variables; auto generated
+.ca end
+ .fi
+
+
+ .** set up for an index when using pfm and snare file is defined
+ .if pfm
+ .** {X}fm macro definitions are too big
+ .dh 1 p=14 s=2,1 e=off
+ .dh 2 p=12 s=1,.5
+ .dh 3 p=&{textsize!10} s=1,0
+
+ .if index_snare_file
+ .ix space .sp 1 .cc 5 %c .ln ^: .sp 0
+ .ix term .br %s `^` ^`` %d
+ .ix groupb .sp .5 %s .br .ll -.25i .in +.25i
+ .ix groupe .sp .1 .in -.25i .ll +.25i
+ .if ! index_cols
+ .dv index_cols 2
+ .fi
+
+ .dv index_col_width [ 6.5 &index_cols / .25 &index_cols 1 - * - ]
+ .dv index_here .pa .ju off .st &textsize .cd 1 i=1i w=7 ^: .h1 INDEX ^: .pn off .lw 0 .sp 0 .tt ^: .cd &index_cols i=1i w=&{index_col_width}i g=.25i ^: .in -i .ll &{index_col_width}i .ix insert
+ .im &index_snare_file
+ .fi
+ .fi
+
+.fi
diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst
new file mode 100644
index 0000000..d314595
--- /dev/null
+++ b/docs/rel-notes.rst
@@ -0,0 +1,25 @@
+=============
+RELEASE NOTES
+=============
+
+E2AP Library Release Notes
+==========================
+The following is a list of release highlights for the platform
+e2ap library.
+
+Dawn Release
+============
+
+2021 8 February
+---------------
+Added CMake support for library generation (RIC-xxx)
+
+
+Cherry Release
+==============
+
+
+2020 November 13; Version 0.0.1
+-------------------------------
+Initial commit of base files (RIC-683)
+
diff --git a/rmr-version.yaml b/rmr-version.yaml
new file mode 100644
index 0000000..aedd70c
--- /dev/null
+++ b/rmr-version.yaml
@@ -0,0 +1,6 @@
+# Communicate to CI which version of RMR to install in the build/vet environment
+# there shouldn't be anything to depend on/use RMR in generating packages, so the
+# version here may lag without effect.
+#
+---
+version: 4.5.2
diff --git a/src/README b/src/README
new file mode 100644
index 0000000..6faaa14
--- /dev/null
+++ b/src/README
@@ -0,0 +1,3 @@
+
+The directories under this level contain GENERATED source code.
+Edits will likely be lost.
diff --git a/test/README b/test/README
new file mode 100644
index 0000000..425435a
--- /dev/null
+++ b/test/README
@@ -0,0 +1,6 @@
+
+There are no unit tests for the generated code.
+
+Driving unit tests is a part of teh CI process, so it is assumed
+that a dummy script in this directory is needed such that it can
+be run during some CI process.
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..00d06df
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,34 @@
+# This work is licensed under a Creative Commons Attribution 4.0 International License.
+# SPDX-License-Identifier: CC-BY-4.0
+# Copyright (C) 2019 AT&T Intellectual Property
+# documentation only
+
+[tox]
+minversion = 2.0
+envlist =
+ docs,
+ docs-linkcheck,
+skipsdist = true
+
+[testenv:docs]
+basepython = python3
+deps =
+ sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+
+commands =
+ sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
+whitelist_externals = echo
+
+[testenv:docs-linkcheck]
+basepython = python3
+deps = sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck