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 <rb2745@att.com>

diff --git a/docs/OCLIP.rst b/docs/OCLIP.rst
index 72ec9cf..9a5d9fe 100644 (file)
--- 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 c4c0432..14197f8 100644 (file)
--- 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 12a340d..6562dd8 100644 (file)
--- 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 db5c96a..0dec1cd 100644 (file)
--- 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 268bfda..2b3b134 100644 (file)
--- 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 4c10e76..e345e62 100644 (file)
--- 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 34cc631..f1b0f54 100644 (file)
--- 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 b6864f0..dc02bcc 100644 (file)
--- 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 9c92fbd..7e541e8 100644 (file)
--- 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 5d649ea..c907172 100644 (file)
--- 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 (file)
index 0000000..3938932
--- /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 <https://jira.onap.org/browse/CIMAN-65>`_ and a sentence explaining what this defect is addressing.
+**Known Issues**
+       - `CIMAN-65 <https://jira.onap.org/browse/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 <https://cve.mitre.org>`_
+
+
+**Upgrade Notes**
+
+**Deprecation Notes**
+
+**Other**
+
+===========
+
+End of Release Notes

diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 3e9c89f..3e9b7ac 100644 (file)
--- 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
 ==============