Restructure documentation and update getting started page to be same …

…as github README (#296) * Add documentation for YDK C++ services, providers, types * Make generate.py executable * Delete unused files * Set YDK C++ version to 0.1.0 * Remove --profile option from generate.py * Update python sanity tests
CiscoDevNet · Nov 10, 2016 · a62276b · a62276b
1 parent 3c500d2
commit a62276b
Show file tree

Hide file tree

Showing 199 changed files with 4,379 additions and 5,865 deletions.
diff --git a/README.md b/README.md
@@ -6,17 +6,16 @@
 [![Coverage Status](https://coveralls.io/repos/github/CiscoDevNet/ydk-gen/badge.svg?branch=master)](https://coveralls.io/github/CiscoDevNet/ydk-gen?branch=master)
 
 
-**ydk-gen** is a developer tool that can generate API bindings to YANG data models for, today, Python. Work is underway to support C++, and the ydk-gen may be used as the starting point for supporting bindings to any language.
+**ydk-gen** is a developer tool that can generate API bindings to YANG data models for, today, Python and C++, with planned future support for other language bindings.
 
 Other tools and libraries are used to deliver ydk-gen's functionality. In particular:
 
-* YANG model analysis and code generation is implemented as an extension to [pyang](https://github.com/mbj4668/pyang)
-* Core libraries are built on [ncclient](https://github.com/ncclient/ncclient)
+* YANG model analysis and code generation is implemented using APIs from the [pyang](https://github.com/mbj4668/pyang) library
 * Documentation is generated using [Sphinx](http://www.sphinx-doc.org/en/stable/)
 
 Of course, many other libraries are used as an integral part of ydk-gen and its dependencies, too many to mention!
 
-Developers can either use pre-packaged generated code (e.g. [ydk-py](http://cs.co/ydk-py)), or they can define the YANG models that code is to be generated for are specified in a profile file. This gives a developer the ability to customize the scope of their SDK based on their requirements.
+The output of ydk-gen is either a core package, that defines services and providers, or a module bundle, consisting of APIs based on YANG models. Each module bundle is generated using a bundle profile and the ydk-gen tool. Developers can either use pre-packaged generated bundles (e.g. [ydk-py](http://cs.co/ydk-py)), or they can define their own bundle, consisting of a set of YANG models, using a bundle profile (e.g. [```ietf_0_1_1.json```](profiles/bundles/ietf_0_1_1.json)). This gives a developer the ability to customize the scope of their bundle based on their requirements.
 
 
 ##System Requirements:
@@ -55,7 +54,7 @@ $ pip install -r requirements
 ## Usage
 
 ```
-$ python generate.py --help
+$ ./generate.py --help
 Usage: generate.py [options]
 
 Options:
@@ -64,7 +63,7 @@ Options:
   -p, --python        Generate Python bundle/core. This is currently the default option
   -c, --cpp           Generate C++ bundle/core
   --core              Install the python/C++ core
-  --bundle=PROFILE    Take options from a profile file
+  --bundle=PROFILE    Take options from a bundle profile file describing YANG
   --sudo              Use superuser permission (during C++ bundle/core generation if necessary)
   -v, --verbose       Verbose mode
   --generate-doc      Generation documentation
@@ -74,7 +73,7 @@ Options:
 ### Installing the YDK core
 
 ```
-python generate.py --core
+ ./generate.py --core
 ```
 
 ### Bundle profiles
@@ -84,7 +83,7 @@ python generate.py --core
 2. Generate the bundle using a command of the form:
 
 ```
-python generate.py --python --bundle profiles/bundles/ietf_0_1_1.json
+./generate.py --python --bundle profiles/bundles/ietf_0_1_1.json
 ```
 
 The generated bundle will in ```ydk-gen/gen-api/python``` or ```ydk-gen/gen-api/cpp```.
@@ -117,7 +116,7 @@ The sample below shows the use of git sources only.
 We have a list of git sources. Each source must specify a URL. This URL should be one that allows the repository to be cloned without requiring user intervention, so please use a public URL such as the example below. There are three further options that can be specified:
 
 - ```commitid``` - Optional specification of a commit in string form. The files identified will be copied from the context of this commit.
-- ```dir``` - List of **relative** directory paths within git repository. All .yang files in this directory **and any sub-directories** will be pulled into the generated SDK.
+- ```dir``` - List of **relative** directory paths within git repository. All .yang files in this directory **and any sub-directories** will be pulled into the generated bundle.
 - ```file```- List of **relative** file paths within the git repository.
 
 Only directory examples are shown below.
@@ -143,30 +142,16 @@ Only directory examples are shown below.
 
 ## Notes
 
-YANG Development Kit Generator:
-
-- This is a tool that generates different language bindings (Python, C++ etc). Developers can use these objects/APIs, to write applications
-- Also provided are runtime libraries including "services" and "service providers".
-    - ServiceProvider: Provides concrete implementation that abstracts underlying protocol details (e.g. `NetconfServiceProvider`, which is based on the NETCONF protocol) 
-    - Services: Provides simple API interface to be used with the bindings and providers
-
-
 ### Python version
 
 - If your environment has both python 2 and python 3 and uses python 2 by default, you may need to use 'python3' and 'pip3' instead of 'python' and 'pip' in the commands mentioned in this document.
 
-For Python entities and netconf session, CRUD service invoked on python class will:
-
-- Encode python data objects to netconf XML payload
-- Perform transport operation with device, collect the netconf response,
-- Decode netconf response in python class, return result to python app.
-
 
-## Directory Structure
+### Directory Structure
 
 ```
 README          - install and usage notes
-gen-api         - generated SDK
+gen-api         - generated bundle/core
 					- python (Python SDK)
 					- cpp (C++ SDK)
 
@@ -183,10 +168,10 @@ test            - test code
 ### Python
 First, generate and install the [test](profiles/test/ydktest.json) bundle and core package
 ```
-$ python generate.py --core
+$ ./generate.py --core
 $ pip install gen-api/python/core/dist/ydk*.tar.gz
 
-$ python generate.py --bundle profiles/test/ydktest.json
+$ ./generate.py --bundle profiles/test/ydktest.json
 $ pip install gen-api/python/ydktest-bundle/dist/ydk*.tar.gz
 ```
 
@@ -202,8 +187,8 @@ $ python test/test_sanity_filters.py
 ### C++
 First, install the [test](profiles/test/ydktest-cpp.json) bundle and core package
 ```
-$ python generate.py --core --cpp
-$ python generate.py --bundle profiles/test/ydktest-cpp.json --cpp
+$./generate.py --core --cpp
+$./generate.py --bundle profiles/test/ydktest-cpp.json --cpp
 ```
 
 To run the core and bundle tests, do the following

diff --git a/generate.py b/generate.py
@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+#
 #  ----------------------------------------------------------------
 # Copyright 2016 Cisco Systems
 #
@@ -186,8 +188,9 @@ def create_shared_libraries(output_directory, sudo):
     os.chdir(cmake_build_dir)
     sudo_cmd = 'sudo' if sudo else ''
     try:
-        subprocess.check_call(['cmake', '..'])
-        subprocess.check_call(['make', '-j5'])
+        FNULL = open(os.devnull, 'w')
+        subprocess.check_call(['cmake', '..'], stdout=FNULL, stderr=FNULL)
+        subprocess.check_call(['make', '-j5'], stdout=FNULL, stderr=FNULL)
         subprocess.check_call(['%s' % sudo_cmd, 'make', 'install'])
     except subprocess.CalledProcessError as e:
         print('\nERROR: Failed to create shared library!\n')
@@ -215,20 +218,15 @@ def _get_time_taken(start_time):
     parser = OptionParser(usage="usage: %prog [options]",
                           version="%prog 0.4.0")
 
-    parser.add_option("--profile",
-                      type=str,
-                      dest="profile",
-                      help="Take options from a profile file, any CLI targets ignored")
-
     parser.add_option("--bundle",
                       type=str,
                       dest="bundle",
-                      help="Take options from a bundle file, any CLI targets ignored")
+                      help="Specify a bundle profile file to generate a bundle from")
 
     parser.add_option("--core",
                       action='store_true',
                       dest="core",
-                      help="Take options from a bundle file, any CLI targets ignored")
+                      help="Generate and/or install core library")
 
     parser.add_option("--output-directory",
                       type=str,
@@ -306,16 +304,7 @@ def _get_time_taken(start_time):
     elif options.python:
         language = 'python'
 
-    if options.profile:
-        output_directory = (YdkGenerator(
-                            output_directory,
-                            ydk_root,
-                            options.groupings_as_class,
-                            options.gentests,
-                            language,
-                            'profile').generate(options.profile))
-
-    elif options.bundle:
+    if options.bundle:
         output_directory = (YdkGenerator(
                             output_directory,
                             ydk_root,

diff --git a/profiles/test/deviation.json b/profiles/test/deviation.json
@@ -1,6 +1,7 @@
 {
     "name": "deviation",
     "version": "0.1.0",
+    "ydk_version":"0.5.1",
     "Author": "Cisco",
     "Copyright": "Cisco",
     "Description": "YDK Test Profile",

diff --git a/profiles/test/ydktest.json b/profiles/test/ydktest.json
@@ -1,6 +1,7 @@
 {
     "name": "ydktest",
-    "version": "0.4.0",
+    "version": "0.5.1",
+    "ydk_version":"0.5.1",
     "Author": "Cisco",
     "Copyright": "Cisco",
     "Description": "YDK Test Profile",

diff --git a/sdk/cpp/packages/CMakeLists.txt b/sdk/cpp/packages/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 2.8.9)
 cmake_policy(SET CMP0048 NEW)
-project(ydk_@BRIEF_NAME@ VERSION 0.5.0)
+project(ydk_@BRIEF_NAME@ VERSION 0.5.1)
 
 
 
@@ -9,7 +9,7 @@ set(YDK_@BRIEF_NAME_CAP@_DESCRIPTION "openconfig ydk bundle")
 # set version
 set(YDK_@BRIEF_NAME_CAP@_MAJOR_VERSION 0)
 set(YDK_@BRIEF_NAME_CAP@_MINOR_VERSION 5)
-set(YDK_@BRIEF_NAME_CAP@_SERVICE_VERSION 0)
+set(YDK_@BRIEF_NAME_CAP@_SERVICE_VERSION 1)
 set(YDK_@BRIEF_NAME_CAP@_VERSION ${YDK_@BRIEF_NAME_CAP@_MAJOR_VERSION}.${YDK_@BRIEF_NAME_CAP@_MINOR_VERSION}.${YDK_@BRIEF_NAME_CAP@_SERVICE_VERSION})
 set(YDK_@BRIEF_NAME_CAP@_CORE_SOVERSION ${YDK_@BRIEF_NAME_CAP@_MAJOR_VERSION}.${YDK_@BRIEF_NAME_CAP@_MINOR_VERSION})
 

diff --git a/sdk/cpp/packages/README.md b/sdk/cpp/packages/README.md
@@ -0,0 +1,14 @@
+<a href="https://github.com/CiscoDevNet/ydk-gen"><img src="https://cloud.githubusercontent.com/assets/17089095/14834057/2e1fe270-0bb7-11e6-9e94-73dd7d71e87d.png" height="240" width="240" ></a>
+
+# YDK bundle
+
+YDK bundle is a package of python API's that are modeled in YANG.
+
+# Installation
+
+Create a build directory to build the library and install it:
+```
+    $ mkdir build && cd build
+    $ cmake .. && sudo make install
+```
+
diff --git a/sdk/cpp/packages/README.rst b/sdk/cpp/packages/README.rst
diff --git a/sdk/cpp/packages/docsgen/_ext b/sdk/cpp/packages/docsgen/_ext
diff --git a/sdk/cpp/packages/docsgen/_templates b/sdk/cpp/packages/docsgen/_templates
diff --git a/sdk/cpp/packages/docsgen/about_ydk.rst b/sdk/cpp/packages/docsgen/about_ydk.rst
diff --git a/sdk/cpp/packages/docsgen/core.rst b/sdk/cpp/packages/docsgen/core.rst