Example documentation for LSOAPI

Change-Id: I58bd3aa451be6e50d764b2db519d234739d628a4
Signed-off-by: Fatih Degirmenci <fatih.degirmenci@ericsson.com>

6 files changed, 45 insertions, 128 deletions

diff --git a/docs/dev-notes.rst b/docs/dev-notes.rst
new file mode 100644
index 0000000..25c24cc
--- /dev/null
+++ b/docs/dev-notes.rst
@@ -0,0 +1,11 @@
+====================================================
+REST Clients Notes : CoSClient, EvcClient, EplClient
+====================================================
+1. Provide rest communications to cosmgr, evcmgr, and eplmgr repsectivly.
+   - provide create/request/update/delete capabilities
+   - these services must be running within tomcat
+   - each has it's own separate war file
+2. Creating resources
+   - The create() methods take cos/epl/evc objects as inputs
+   - Not all inputs are known at time of resource creation, and the create service itself will set some of the parameters, and the all return object of the type that was created which will capture any values set within the create service (in addition to remembering the values originally supplied)
+   - You must capture the object returned by the create function, as there will be values that were set during that proccess
diff --git a/docs/etc/conf.py b/docs/etc/conf.py
deleted file mode 100644
index f8c8c11..0000000
--- a/docs/etc/conf.py
+++ /dev/null
@@ -1,34 +0,0 @@
-import datetime
-import sys
-import os
-
-try:
-    __import__('imp').find_module('sphinx.ext.numfig')
-    extensions = ['sphinx.ext.numfig']
-except ImportError:
-    # 'pip install sphinx_numfig'
-    extensions = ['sphinx_numfig']
-
-# numfig:
-number_figures = True
-figure_caption_prefix = "Fig."
-
-source_suffix = '.rst'
-master_doc = 'index'
-pygments_style = 'sphinx'
-html_use_index = False
-
-pdf_documents = [('index', u'LSOAPI', u'LSOAPI Project', u'OPNFV')]
-pdf_fit_mode = "shrink"
-pdf_stylesheets = ['sphinx','kerning','a4']
-#latex_domain_indices = False
-#latex_use_modindex = False
-
-latex_elements = {
-    'printindex': '',
-}
-
-project = u'LSOAPI: Connectivity Services LSO'
-copyright = u'%s, OPNFV' % datetime.date.today().year
-version = u'1.0.0'
-release = u'1.0.0'
diff --git a/docs/etc/opnfv-logo.png b/docs/etc/opnfv-logo.png
deleted file mode 100644
index 1519503..0000000
--- a/docs/etc/opnfv-logo.png
+++ /dev/null
diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
deleted file mode 100644
index 1d1ca6d..0000000
--- a/docs/how-to-use-docs/documentation-example.rst
+++ /dev/null
@@ -1,86 +0,0 @@
-.. two dots create a comment. please leave this logo at the top of each of your rst files.
-.. image:: ../etc/opnfv-logo.png
-  :height: 40
-  :width: 200
-  :alt: OPNFV
-  :align: left
-.. these two pipes are to seperate the logo from the first title
-|
-|
-How to create documentation for your OPNFV project
-==================================================
-
-this is the directory structure of the docs/ directory that can be found in the root of your project directory
-
-.. code-block:: bash
-
-    ./etc
-    ./etc/opnfv-logo.png
-    ./etc/conf.py
-    ./how-to-use-docs
-    ./how-to-use-docs/documentation-example.rst
-    ./how-to-use-docs/index.rst
-
-To create your own documentation, Create any number of directories (depending on your need) and place in each of them an index.rst.
-This index file must refence your other rst files.
-
-* Here is an example index.rst
-
-.. code-block:: bash
-
-  Example Documentation table of contents
-  =======================================
-
-  Contents:
-
-  .. toctree::
-     :numbered:
-     :maxdepth: 4
-
-     documentation-example.rst
-
-  Indices and tables
-  ==================
-
-  * :ref:`search`
-
-  Revision: _sha1_
-
-  Build date: |today|
-
-
-The Sphinx Build
-================
-
-When you push documentation changes to gerrit a jenkins job will create html documentation.
-
-* Verify Jobs
-For verify jobs a link to the documentation will show up as a comment in gerrit for you to see the result.
-
-* Merge jobs
-
-Once you are happy with the look of your documentation you can submit the patchset the merge job will
-copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html
-
-Here are some quick examples of how to use rst markup
-
-This is a headline::
-
-  here is some code, note that it is indented
-
-links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/
-
-* Bulleted Items
-
-  **this will be bold**
-
-.. code-block:: bash
-
-  echo "Heres is a code block with bash syntax highlighting"
-
-
-Leave these at the bottom of each of your documents they are used internally
-
-Revision: _sha1_
-
-Build date: |today|
diff --git a/docs/how-to-use-docs/index.rst b/docs/index.rst
index 36710b3..1b84735 100644
--- a/docs/how-to-use-docs/index.rst
+++ b/docs/index.rst
@@ -3,25 +3,23 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. image:: ../etc/opnfv-logo.png
+.. image:: opnfv-logo.png
   :height: 40
   :width: 200
   :alt: OPNFV
   :align: left
 
-Example Documentation table of contents
-=======================================
+Connectivity Services LSO
+=========================
 
 Contents:
 
 .. toctree::
-   :numbered:
    :maxdepth: 4
+   :titlesonly:
 
-   documentation-example.rst
-
-Indices and tables
-==================
+   dev-notes.rst
+   state-of-code.rst
 
 * :ref:`search`
 
diff --git a/docs/state-of-code.rst b/docs/state-of-code.rst
new file mode 100644
index 0000000..2978c48
--- /dev/null
+++ b/docs/state-of-code.rst
@@ -0,0 +1,28 @@
+============
+Introduction
+============
+
+This is a proof of concept prototype implementation enabling the creation and management of MEF EPL Services.
+
+Being a proof of concept prototype, there are some areas which have received only superficial coverage or no coverage at all.  Following are items that should be addressed when evolving this to a production oriented implementation
+
+1. The current test suite is reasonable, but exhaustive.  Production targeted version should have more thourough test coverage
+2. Exception handling is only superficially implemented.  A production system should include a more robust exception handling and error reporting architecture
+3. Only a subset of the MEF Attributes have been implemented.  Long term the goal is to evolve this code base to fully support all MEF paramaters
+4. We are only implementing a portion of the data model for the sake of expediency.
+    - Only EPL service is supported at the moment
+    - Currently, the service repo is hard coded to hold EPL (we have not implemented the more general MEFSvc and Eline/ELine/Tree classes that in the future will also reside in the repo).
+        - The MEF service hierarchy (MEFSvc->Eline->EPL) need to be architected and implemented
+        - The SvcMgr needs to be architected in order to handle multiple service types from a REST API perspective and from a persitance perspective
+    - the REST URL/path architecture is currently hard coded, should be configurable at some point (config file, etc).
+5. There has not been a definitive analysis of which specific service attributes are recieved, generated, or queried at each service layer.
+    - It would be very useful to do this analysis, and then reflect in the code through structure and documentation, which attributes are set/queried at each layer
+
+==============
+Specific To Do
+==============
+1. Who supplies/generates evcMaxSvcFrameSize?  Currently hard coded to 1600 in EplService.create()
+2. Make sure for all XXXClient.create(xxx), that we capture the returned version, in case the service layer modified it
+    - for example epl = eplClient.create(epl)
+3. Check for nulls when prior to printing out lists in dump() fxns
+4. Unique EVC IDs are being generated via an internal counter.  This of course does not scale nor survive restart.  A proper unique ID generation approach will be needed for production.