From: elinuxhenrik Date: Thu, 20 Oct 2022 13:29:36 +0000 (+0200) Subject: Add documentation X-Git-Tag: 1.0.0~48 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;ds=sidebyside;h=refs%2Fchanges%2F36%2F9336%2F5;p=nonrtric%2Fplt%2Fsme.git Add documentation Issue-ID: NONRTRIC-812 Signed-off-by: elinuxhenrik Change-Id: I2a72314bfdee0d13efea7416a43ca37896628a81 --- diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9e770b5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +.vscode +.idea/ +.tox +docs/_build/ +.project +.settings +.pydevproject \ No newline at end of file diff --git a/capifcore/README.md b/capifcore/README.md index 8e65382..5eea851 100644 --- a/capifcore/README.md +++ b/capifcore/README.md @@ -24,9 +24,38 @@ This product is a Go implementation of the CAPIF Core function, based on the 3GPP CAPIF interfaces. -## Run +## Generation of API code + +The CAPIF APIs are generated from the OpenAPI specification provided by 3GPP. The `generate.sh` script downloads the +specifications from 3GPP, fixes them and then generates the APIs. It also generates the mocks needed for unit testing. + +To fix the specifications there are three tools: +- `commoncollector`, collects type definitions from peripheral specifications to keep down the number of dependencies to + other specifications. The types to collect are listed in the `definitions.txt`file. +- `enumfixer`, fixes enumeration definitions so they can be properly generated. +- `specificationfixer`, fixes flaws in the specifications so they can be properly generated. All fixes are hard coded. + +## Build and test -To run the Core Function run the following commands from the top of the repo: +To generate mocks manually, run the following command: + + go generate ./... + +To build the application, run the following command: go build - ./capifcore [-port ] \ No newline at end of file + +To run the unit tests for the application, run the following command: + + go test ./... + +The application can also be built as a Docker image, by using the following command: + + docker build . -t capifcore + +## Run + +To run the Core Function from the command line, run the following commands from this folder. + + ./capifcore [-port ] + diff --git a/capifcore/build-capifcore-ubuntu.sh b/capifcore/build-capifcore-ubuntu.sh index 0973e2a..d682f2f 100755 --- a/capifcore/build-capifcore-ubuntu.sh +++ b/capifcore/build-capifcore-ubuntu.sh @@ -19,10 +19,12 @@ set -eux echo "--> build-capifcore-ubuntu.sh" + # go installs tools like go-acc to $HOME/go/bin # ubuntu minion path lacks go export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin go version +cd capifcore/ # install the go coverage tool helper go get -v github.com/ory/go-acc diff --git a/capifcore/generate.sh b/capifcore/generate.sh index 9a54322..4726ccb 100755 --- a/capifcore/generate.sh +++ b/capifcore/generate.sh @@ -165,3 +165,6 @@ oapi-codegen --config gogeneratorspecs/aefsecurityapi/generator_settings_server. echo "Cleanup" rm -rf specs + +echo "Generating mocks." +go generate ./... \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/aefsecurityapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/aefsecurityapi/generator_settings_client.yaml deleted file mode 100644 index 6f7c966..0000000 --- a/capifcore/gogeneratorspecs/aefsecurityapi/generator_settings_client.yaml +++ /dev/null @@ -1,27 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/aefsecurityapi/aefsecurityapi-client.gen.go -package: aefsecurityapi -generate: - - server -import-mapping: - TS29571_CommonData.yaml: internal/common29571 diff --git a/capifcore/gogeneratorspecs/auditingapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/auditingapi/generator_settings_client.yaml deleted file mode 100644 index d7b9704..0000000 --- a/capifcore/gogeneratorspecs/auditingapi/generator_settings_client.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/auditingapi/auditingapi-client.gen.go -package: auditingapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - TS29222_CAPIF_Publish_Service_API.yaml: internal/publishserviceapi - TS29222_CAPIF_Logging_API_Invocation_API.yaml: internal/loggingapi \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/discoverserviceapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/discoverserviceapi/generator_settings_client.yaml deleted file mode 100644 index e7231b8..0000000 --- a/capifcore/gogeneratorspecs/discoverserviceapi/generator_settings_client.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/discoverserviceapi/discoverserviceapi-client.gen.go -package: discoverserviceapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - TS29222_CAPIF_Publish_Service_API.yaml: internal/publishserviceapi \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/eventsapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/eventsapi/generator_settings_client.yaml deleted file mode 100644 index 8e88252..0000000 --- a/capifcore/gogeneratorspecs/eventsapi/generator_settings_client.yaml +++ /dev/null @@ -1,25 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/eventsapi/eventsapi-client.gen.go -package: eventsapi -generate: - - client \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/invokermanagementapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/invokermanagementapi/generator_settings_client.yaml deleted file mode 100644 index fdce27c..0000000 --- a/capifcore/gogeneratorspecs/invokermanagementapi/generator_settings_client.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/invokermanagementapi/invokermanagementapi-client.gen.go -package: invokermanagementapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - TS29222_CAPIF_Publish_Service_API.yaml: internal/publishserviceapi \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/loggingapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/loggingapi/generator_settings_client.yaml deleted file mode 100644 index f9be788..0000000 --- a/capifcore/gogeneratorspecs/loggingapi/generator_settings_client.yaml +++ /dev/null @@ -1,25 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/loggingapi/loggingapi-client.gen.go -package: loggingapi -generate: - - client \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/providermanagementapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/providermanagementapi/generator_settings_client.yaml deleted file mode 100644 index 58c4b60..0000000 --- a/capifcore/gogeneratorspecs/providermanagementapi/generator_settings_client.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/providermanagementapi/providermanagementapi-client.gen.go -package: providermanagementapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/publishserviceapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/publishserviceapi/generator_settings_client.yaml deleted file mode 100644 index eee5e6d..0000000 --- a/capifcore/gogeneratorspecs/publishserviceapi/generator_settings_client.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/publishserviceapi/publishserviceapi-client.gen.go -package: publishserviceapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - CommonData.yaml: internal/common \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/routinginfoapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/routinginfoapi/generator_settings_client.yaml deleted file mode 100644 index 66c56bc..0000000 --- a/capifcore/gogeneratorspecs/routinginfoapi/generator_settings_client.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/routinginfoapi/routinginfoapi-client.gen.go -package: routinginfoapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - TS29222_CAPIF_Publish_Service_API.yaml: internal/publishserviceapi \ No newline at end of file diff --git a/capifcore/gogeneratorspecs/securityapi/generator_settings_client.yaml b/capifcore/gogeneratorspecs/securityapi/generator_settings_client.yaml deleted file mode 100644 index 409e527..0000000 --- a/capifcore/gogeneratorspecs/securityapi/generator_settings_client.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# - -# ========================LICENSE_START================================= -# O-RAN-SC -# %% -# Copyright (C) 2022: Nordix Foundation -# %% -# 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. -# ========================LICENSE_END=================================== -# - -output: - internal/securityapi/securityapi-client.gen.go -package: securityapi -generate: - - client -import-mapping: - TS29122_CommonData.yaml: internal/common29122 - TS29571_CommonData.yaml: internal/common29571 - TS29222_CAPIF_Publish_Service_API.yaml: internal/publishserviceapi \ No newline at end of file diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..c3b6ce5 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cce3ae6 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,35 @@ +# ============LICENSE_START=============================================== +# Copyright (C) 2022 Nordix Foundation. All rights reserved. +# ======================================================================== +# 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. +# ============LICENSE_END================================================= +# + +from docs_conf.conf import * + +#branch configuration + +branch = 'latest' + +linkcheck_ignore = [ + 'http://localhost.*', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*', +] + +extensions = ['sphinx.ext.intersphinx',] + +#intershpinx mapping with other projects +intersphinx_mapping = {} + +intersphinx_mapping['nonrtric'] = ('https://docs.o-ran-sc.org/projects/o-ran-sc-nonrtric/en/%s' % branch, None) diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..de2956f --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: nonrtric-plt-sme diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..e000937 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2022 Nordix + +Developer Guide +=============== + +This document provides a quick start for developers of the Non-RT RIC Service Management and Exposure. + +Additional developer guides are available on the `O-RAN SC NONRTRIC Developer wiki `_. + +To build and run the CAPIF Core implementation, see the README.md file in the "capifcore" folder. diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..00b0fd0 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..80a74fe --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2022 Nordix + +Non-RT RIC Service Management and Exposure (SME) +================================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./overview.rst + ./developer-guide.rst + ./release-notes.rst diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..dd1cfc0 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2022 Nordix + +Overview +~~~~~~~~ + +Within Service Management and Exposure the CAPIF Core product is developed. It resides in the "capifcore" folder. + + +This product is a part of :doc:`NONRTRIC `. diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..0bad889 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,34 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2022 Nordix + +============= +Release-Notes +============= + + +This document provides the release notes for the Non-RT RIC CAPIF Core. + +Version history Service Management and Exposure +=============================================== + ++------------+----------+------------------+-----------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++------------+----------+------------------+-----------------+ +| 2022-??-?? | 1.0.0 | Henrik Andersson | G Release | +| | | | Initial version | ++------------+----------+------------------+-----------------+ + +Release Data +============ + +G Release +--------- ++-----------------------------+---------------------------------------------------+ +| **Project** | Non-RT RIC CAPIF Core | +| | | ++-----------------------------+---------------------------------------------------+ +| **Repo/commit-ID** | nonrtric/plt/sme/???????? | +| | | ++-----------------------------+---------------------------------------------------+ diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..a97db93 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,10 @@ +tox +Sphinx +doc8 +docutils +setuptools +six +sphinx_rtd_theme +sphinxcontrib-needs +sphinx_bootstrap_theme +lfdocs-conf \ No newline at end of file diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..a607d74 --- /dev/null +++ b/tox.ini @@ -0,0 +1,37 @@ +# ================================================================================== +# Copyright (c) 2022 Nordix +# +# 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. +# ================================================================================== + +# documentation only +[tox] +minversion = 2.0 +envlist = + docs, + docs-linkcheck, +skipsdist = true + +[testenv:docs] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt + +commands = + sphinx-build -W -b html -n -d {envtmpdir}/docs/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = echo + +[testenv:docs-linkcheck] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt +commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck