[VOL-2876]
Documentation cleanup and more compliant swagger docs
Update to python3 venv and Sphinx to build docs
(Cherry pick of https://gerrit.opencord.org/c/18434/ without root
Makefile changes)
Change-Id: I625179608c918c2889f31711624e93477d493c07
diff --git a/docs/Makefile b/docs/Makefile
index 13176dc..a2df413 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,9 +17,8 @@
$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
doc_venv:
- virtualenv $@ ;\
+ virtualenv -p python3 $@ ;\
source $@/bin/activate ;\
- pip install livereload ;\
pip install -r requirements.txt
lint: doc8
diff --git a/docs/requirements.txt b/docs/requirements.txt
index cc4662f..fcb72ba 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,15 +1,13 @@
-Sphinx~=1.8.5
-actdiag~=0.5.4
+Sphinx~=2.4.4
+actdiag~=2.0.0
blockdiag~=1.5.4
-livereload~=2.6.1
-nwdiag~=1.0.4
-recommonmark~=0.6.0
doc8~=0.8.0
-seqdiag~=0.9.6
-sphinx-reload~=0.2.0
+nwdiag~=2.0.0
+recommonmark~=0.6.0
+seqdiag~=2.0.0
sphinx-rtd-theme~=0.4.3
-sphinxcontrib-actdiag~=0.8.5
-sphinxcontrib-blockdiag~=1.5.5
-sphinxcontrib-nwdiag~=0.9.5
-sphinxcontrib-seqdiag~=0.8.5
-sphinxcontrib-openapi~=0.5.0
+sphinxcontrib-actdiag~=2.0.0
+sphinxcontrib-blockdiag~=2.0.0
+sphinxcontrib-nwdiag~=2.0.0
+sphinxcontrib-openapi~=0.6.0
+sphinxcontrib-seqdiag~=2.0.0
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8eec878..960d4bf 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to BBSim's documentation!
-=================================
+BBSim, a Broadband Simulator
+============================
.. toctree::
:maxdepth: 2
@@ -178,8 +178,9 @@
Controlled PON and ONU activation
---------------------------------
-BBSim provides support for controlled PON and ONU activation. By default both PON ports and ONUs are automatically activated when OLT is enabled.
-This can be controlled using ``-ca`` option.
+BBSim provides support for controlled PON and ONU activation. By default both
+PON ports and ONUs are automatically activated when OLT is enabled. This can
+be controlled using ``-ca`` option.
``-ca`` can be set to one of below four modes:
@@ -188,21 +189,28 @@
- only-onu: PON ports automatically enabled and ONUs dynamically activated
On Enable OLT, IntfIndications for all PON ports are sent but ONU discovery indications are not sent.
When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
+
- only-pon: PON ports dynamically enabled and ONUs automatically activated
On Enable OLT, neither IntfIndications for PON ports nor ONU discovery indications are sent.
When EnablePonIf request is received at OpenOLT server, then that PON port is enabled and
IntfIndication is sent for that PON and all ONUs under that ports are discovered automatically.
+
- both: Both PON ports and ONUs are dynamically activated
On Enable OLT, neither IntfIndication for PON ports nor ONU discovery indications are sent.
- When EnablePonIf request is received on OpenOLT server then IntfIndication is sent for that PON but no ONU discovery indication will be sent.
+ When EnablePonIf request is received on OpenOLT server then
+ IntfIndication is sent for that PON but no ONU discovery indication
+ will be sent.
When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
Publishing BBSim Events on kafka
--------------------------------
-BBSim provides option for publishing events on kafka. To publish events on kafka, set BBSimEvents flag and configure kafkaAddress.
-Once BBSim is started, it will publish events (as and when they happen) on topic ``BBSim-OLT-<id>-Events``.
+BBSim provides option for publishing events on kafka. To publish events on
+kafka, set BBSimEvents flag and configure kafkaAddress.
+
+Once BBSim is started, it will publish events (as and when they happen) on
+topic ``BBSim-OLT-<id>-Events``.
Types of Events:
- OLT-enable-received
diff --git a/docs/swagger/bbsim/bbsim.swagger.json b/docs/swagger/bbsim/bbsim.swagger.json
index d4130f1..2dfc235 100644
--- a/docs/swagger/bbsim/bbsim.swagger.json
+++ b/docs/swagger/bbsim/bbsim.swagger.json
@@ -21,12 +21,6 @@
"schema": {
"$ref": "#/definitions/bbsimOlt"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -44,12 +38,6 @@
"schema": {
"$ref": "#/definitions/bbsimFlows"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -75,12 +63,6 @@
"schema": {
"$ref": "#/definitions/bbsimONUs"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -96,12 +78,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -117,12 +93,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -140,12 +110,6 @@
"schema": {
"$ref": "#/definitions/bbsimONU"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -169,12 +133,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -198,12 +156,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -229,12 +181,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -272,12 +218,6 @@
"schema": {
"$ref": "#/definitions/bbsimFlows"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -303,12 +243,6 @@
"schema": {
"$ref": "#/definitions/bbsimONUTrafficSchedulers"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -334,12 +268,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -364,12 +292,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -396,12 +318,6 @@
"schema": {
"$ref": "#/definitions/bbsimResponse"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -430,6 +346,23 @@
]
}
},
+ "/v1/olt/reboot": {
+ "post": {
+ "summary": "Reboot OLT",
+ "operationId": "RebootOlt",
+ "responses": {
+ "200": {
+ "description": "A successful response.",
+ "schema": {
+ "$ref": "#/definitions/bbsimResponse"
+ }
+ }
+ },
+ "tags": [
+ "BBSim"
+ ]
+ }
+ },
"/v1/olt/status": {
"get": {
"summary": "Get current status of OLT",
@@ -440,12 +373,6 @@
"schema": {
"$ref": "#/definitions/bbsimOlt"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -463,12 +390,6 @@
"schema": {
"$ref": "#/definitions/bbsimVersionNumber"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -842,39 +763,6 @@
}
}
},
- "protobufAny": {
- "type": "object",
- "properties": {
- "type_url": {
- "type": "string"
- },
- "value": {
- "type": "string",
- "format": "byte"
- }
- }
- },
- "runtimeError": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string"
- },
- "code": {
- "type": "integer",
- "format": "int32"
- },
- "message": {
- "type": "string"
- },
- "details": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/protobufAny"
- }
- }
- }
- },
"tech_profileAdditionalBW": {
"type": "string",
"enum": [
diff --git a/docs/swagger/legacy/bbsim.swagger.json b/docs/swagger/legacy/bbsim.swagger.json
index b558518..2873efd 100644
--- a/docs/swagger/legacy/bbsim.swagger.json
+++ b/docs/swagger/legacy/bbsim.swagger.json
@@ -34,12 +34,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -64,12 +58,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -156,12 +144,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -248,12 +230,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -338,12 +314,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -376,12 +346,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -416,12 +380,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -506,12 +464,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -598,12 +550,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -651,12 +597,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -741,12 +681,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -831,12 +765,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -870,12 +798,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -960,12 +882,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1052,12 +968,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1098,12 +1008,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1149,12 +1053,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1220,12 +1118,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"tags": [
@@ -1250,12 +1142,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1300,12 +1186,6 @@
"type": "string",
"format": "string"
}
- },
- "default": {
- "description": "An unexpected error response",
- "schema": {
- "$ref": "#/definitions/runtimeError"
- }
}
},
"parameters": [
@@ -1659,42 +1539,6 @@
}
}
},
- "protobufAny": {
- "type": "object",
- "properties": {
- "type_url": {
- "type": "string",
- "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
- },
- "value": {
- "type": "string",
- "format": "byte",
- "description": "Must be a valid serialized protocol buffer of the above specified type."
- }
- },
- "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := ptypes.MarshalAny(foo)\n ...\n foo := \u0026pb.Foo{}\n if err := ptypes.UnmarshalAny(any, foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }"
- },
- "runtimeError": {
- "type": "object",
- "properties": {
- "error": {
- "type": "string"
- },
- "code": {
- "type": "integer",
- "format": "int32"
- },
- "message": {
- "type": "string"
- },
- "details": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/protobufAny"
- }
- }
- }
- },
"tech_profileAdditionalBW": {
"type": "string",
"enum": [