From dd0f4438e8dea6ef68a043488545e3efcb3fa78a Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Fri, 13 Oct 2017 15:28:09 -0400 Subject: Minor edits to resturcture text documentation Improved cross references, bullet lists, and used code-block directive on bash cmds Added release-notes template Change-Id: Id12fb1b77ef9690b5b50505e47ec7035039f2f24 Issue-ID: CLI-54 Signed-off-by: Rich Bennett --- docs/OCLIP.rst | 5 ++-- docs/OOM_and_HEAT_based_deployment.rst | 5 ++-- docs/architecture.rst | 7 ++--- docs/cmd_help.rst | 7 ++--- docs/console.rst | 4 +-- docs/developer_guide.rst | 9 ++++--- docs/index.rst | 1 + docs/installation_guide.rst | 31 +++++++++++++++------- docs/logging.rst | 5 ++-- docs/open_cli_schema_version_1_0.rst | 13 ++++----- docs/release-notes.rst | 48 ++++++++++++++++++++++++++++++++++ docs/user_guide.rst | 3 ++- 12 files changed, 103 insertions(+), 35 deletions(-) create mode 100644 docs/release-notes.rst diff --git a/docs/OCLIP.rst b/docs/OCLIP.rst index 72ec9cf8..9a5d9fe7 100644 --- a/docs/OCLIP.rst +++ b/docs/OCLIP.rst @@ -1,12 +1,13 @@ -.. _OCLIP: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _OCLIP: + Open CLI Platform (oclip) ========================= .. toctree:: :maxdepth: 1 - open_cli_schema_version_1_0.rst \ No newline at end of file + open_cli_schema_version_1_0.rst diff --git a/docs/OOM_and_HEAT_based_deployment.rst b/docs/OOM_and_HEAT_based_deployment.rst index c4c0432e..14197f8a 100644 --- a/docs/OOM_and_HEAT_based_deployment.rst +++ b/docs/OOM_and_HEAT_based_deployment.rst @@ -1,8 +1,9 @@ -.. _OOM_and_HEAT_based_deployment: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _OOM_and_HEAT_based_deployment: + CLI deployment using OOM and HEAT ================================= @@ -19,4 +20,4 @@ To troubleshoot any issues in CLI, please login to portal_vm and CLI docker runs OOM based deployment -------------------- -ONAL CLI docker image is integrated with OOM and is available under name 'cli' \ No newline at end of file +ONAL CLI docker image is integrated with OOM and is available under name 'cli' diff --git a/docs/architecture.rst b/docs/architecture.rst index 12a340d7..6562dd85 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -1,8 +1,9 @@ -.. _architecture: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _cli_architecture: + CLI architecture ================ @@ -13,11 +14,11 @@ Following diagram shows the high-level architecture of ONAP CLI. :width: 800px * **Command Registrar** : Registrar keeps track of the commands regsitered in ONAP CLI and when user invokes the command, it identify -the corresponding command route the request to that command plugin. + the corresponding command route the request to that command plugin. * **Command Discoverer** : Discoverer discovers the commands both in plug-in format and YAML and auto-matically register them into Registrar. -* **Command Plug-ings** : Implement the command as plugin. More details :ref:`developer_guide` +* **Command Plug-ings** : Implement the command as plugin. More details :ref:`cli_developer_guide` * **HTTP Command** : Plug-in for implementing all Rest based command as YAML without any coding. diff --git a/docs/cmd_help.rst b/docs/cmd_help.rst index db5c96a2..0dec1cd3 100644 --- a/docs/cmd_help.rst +++ b/docs/cmd_help.rst @@ -1,4 +1,3 @@ -.. _cmd_help: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. @@ -8,12 +7,14 @@ :maxdepth: 2 +.. _cli_cmd_help: + onap-1.1 -========================== +======== microservice-create ------------------------------------------------ +------------------- usage: onap microservice-create diff --git a/docs/console.rst b/docs/console.rst index 268bfda0..2b3b1345 100644 --- a/docs/console.rst +++ b/docs/console.rst @@ -2,7 +2,7 @@ .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. -.. _console: +.. _cli_console: CLI Console =========== @@ -21,4 +21,4 @@ After installation, ONAP CLI can be used in following form: .. image:: images/portal-cli-web-con.png :height: 600px - :width: 800px \ No newline at end of file + :width: 800px diff --git a/docs/developer_guide.rst b/docs/developer_guide.rst index 4c10e765..e345e624 100644 --- a/docs/developer_guide.rst +++ b/docs/developer_guide.rst @@ -1,8 +1,9 @@ -.. _developer_guide: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _cli_developer_guide: + CLI developer guide =================== @@ -80,12 +81,12 @@ All ONAP CLI commands can be implemented as YAML using HTTP profile. Follow the steps below to implement new commands in ONAP using YAML: -#. Install the latest ONAP CLI using the guide installation_guide_. +#. Install the latest ONAP CLI using the guide :ref:`cli_installation_guide`. -#. Under the onap-cli-schema folder, add a new YAML file by referring to open_cli_schema_version_1_0_. +#. Under the onap-cli-schema folder, add a new YAML file by referring to :ref:`open_cli_schema_version_1_0`. #. Use the command 'onap schema-validate' to validate the YAML before testing its functionality. #. Run 'onap schema-refresh' command to take the new YAML file. We recommed validating the YAML before running this command. -#. To test this command, run the command 'onap CMD-NAME --help'. \ No newline at end of file +#. To test this command, run the command 'onap CMD-NAME --help'. diff --git a/docs/index.rst b/docs/index.rst index 34cc6319..f1b0f54f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,3 +40,4 @@ ONAP CLI is developed using the industry first CLI platform called installation_guide.rst OOM_and_HEAT_based_deployment.rst logging.rst + release-notes.rst diff --git a/docs/installation_guide.rst b/docs/installation_guide.rst index b6864f05..dc02bcc5 100644 --- a/docs/installation_guide.rst +++ b/docs/installation_guide.rst @@ -1,8 +1,9 @@ -.. _installation_guide: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _cli_installation_guide: + CLI installation guide ====================== @@ -22,15 +23,19 @@ Please follow the instructions given below, for installing CLI using install.sh. .. _here: https://gerrit.onap.org/r/gitweb?p=cli.git;a=blob_plain;f=deployment/zip/installer/install.sh;hb=refs/heads/master -2. Run command:: +2. Run command + +.. code-block:: bash source /tmp/install.sh -3. Verify the installation by running following command:: +3. Verify the installation by running following command. + +.. code-block:: bash onap -v -4. For details, see :ref:`user_guide` +4. For details, see :ref:`cli_user_guide` Using Portal CLI app @@ -52,26 +57,32 @@ Please follow the instructions given below, for installing CLI from portal. 3. After downloading, please follow the instruction given in this page to install ONAP CLI. -4. Verify the installation by running following command:: +4. Verify the installation by running following command + +.. code-block:: bash onap -v -5. For details, see :ref:`user_guide` +5. For details, see :ref:`cli_user_guide` Using docker image ------------------ +------------------ Please follow the instructions given below, for installing CLI using docker image. -1. Download the cli docker image:: +1. Download the cli docker image + +.. code-block:: bash docker login -u docker -p docker nexus3.onap.org:10001 docker pull nexus3.onap.org:10001/onap/cli -2. Verify the installation by running following command:: +2. Verify the installation by running following command + +.. code-block:: bash docker run onap/cli onap -v -3. For details, see :ref:`user_guide` +3. For details, see :ref:`cli_user_guide` diff --git a/docs/logging.rst b/docs/logging.rst index 9c92fbd1..7e541e8b 100644 --- a/docs/logging.rst +++ b/docs/logging.rst @@ -1,11 +1,12 @@ -.. _logging: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _cli_logging: + CLI Logging =========== ONAP CLI provides logging based on slf4j and ONAP_CLI_HOME/conf/logging.properties is used to configure it. -By default it reports the logs under ONAP_CLI_HOME/logs folder. \ No newline at end of file +By default it reports the logs under ONAP_CLI_HOME/logs folder. diff --git a/docs/open_cli_schema_version_1_0.rst b/docs/open_cli_schema_version_1_0.rst index 5d649eaf..c907172e 100644 --- a/docs/open_cli_schema_version_1_0.rst +++ b/docs/open_cli_schema_version_1_0.rst @@ -1,8 +1,9 @@ -.. _open_cli_schema_version_1_0: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _open_cli_schema_version_1_0: + Open Command Line Interface (CLI) Schema Version (OCS) 1.0 ========================================================== @@ -638,11 +639,11 @@ direction printed. It can be: * *portrait* : To print the results in two columns. First column is the name of -the attribute and second column is the value of the attribute. It's more useful -while command does operations like creation of resource, viewing of resources. + the attribute and second column is the value of the attribute. It's more useful + while command does operations like creation of resource, viewing of resources. * *landscape* : To print the results row vise in landscape mode. It's more -useful while command does operations like listing of resource. + useful while command does operations like listing of resource. attributes ~~~~~~~~~~ @@ -691,8 +692,8 @@ there are two scopes: * *short* : attribute configured with this option will always printed by default * *long* : attriuted configured with this option will get printed only when -user inputs the default parameter *long*, defined in *default_parameters* -section. So to print all attributes of a command, user will input parameter: + user inputs the default parameter *long*, defined in *default_parameters* + section. So to print all attributes of a command, user will input parameter: --long diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 00000000..39389326 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,48 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +CLI Release Notes +================= + +.. note:: + * This Release Notes must be updated each time the team decides to Release new artifacts. + * The scope of this Release Notes is for this particular component. In other words, each ONAP component has its Release Notes. + * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of this Release Notes. + * Except the date and the version number, all the other sections are optional but there must be at least one section describing the purpose of this new release. + * This note must be removed after content has been added. + + +Version: x.y.z +-------------- + + +:Release Date: yyyy-mm-dd + + + +**New Features** + +One or two sentences explaining the purpose of this Release. + +**Bug Fixes** + - `CIMAN-65 `_ and a sentence explaining what this defect is addressing. +**Known Issues** + - `CIMAN-65 `_ and two, three sentences. + One sentences explaining what is the issue. + + Another sentence explaining the impact of the issue. + + And an optional sentence providing a workaround. + +**Security Issues** + You may want to include a reference to CVE (Common Vulnerabilities and Exposures) `CVE `_ + + +**Upgrade Notes** + +**Deprecation Notes** + +**Other** + +=========== + +End of Release Notes diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 3e9c89fe..3e9b7aca 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,8 +1,9 @@ -.. _user_guide: .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2017 Huawei Technologies Co., Ltd. +.. _cli_user_guide: + CLI user guide ============== -- cgit 1.2.3-korg