diff --git a/README.md b/README.md
index b7e640f48..ec4f2b710 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,43 @@
+[](https://github.com/CiscoDevNet/ydk-gen/blob/master/LICENSE) [](https://travis-ci.org/CiscoDevNet/ydk-gen)
+[](https://codecov.io/gh/CiscoDevNet/ydk-gen)
+
+
+
+YANG Development Kit (Generator)
+================================
+
**Table of Contents**
-- [YDK-GEN](#ydk-gen)
- - [System requirements](#system-requirements)
- - [Installation](#installation)
- - [Setting up your environment](#setting-up-your-environment)
- - [Clone ydk-gen and install the requirements](#clone-ydk-gen-and-install-the-requirements)
- - [Usage](#usage)
- - [First step: choose your bundle profile](#first-step-choose-your-bundle-profile)
- - [Details](#details)
- - [Second step: Generate & install the core](#second-step-generate--install-the-core)
- - [Third step: Generate & install your bundle](#third-step-generate--install-your-bundle)
- - [Fourth step: Writing your first app](#fourth-step-writing-your-first-app)
- - [Documentation](#documentation)
- - [Notes](#notes)
- - [Python version](#python-version)
- - [Directory structure](#directory-structure)
- - [Troubleshooting](#troubleshooting)
- - [Running Unit Tests](#running-unit-tests)
- - [Python](#python)
- - [C++](#c)
+- [Overview](#overview)
+- [System requirements](#system-requirements)
+ - [Linux](#linux)
+ - [macOS](#macos)
+ - [Windows](#windows)
+- [Installation](#installation)
+ - [Setting up your environment](#setting-up-your-environment)
+ - [Clone ydk-gen and install the requirements](#clone-ydk-gen-and-install-the-requirements)
+- [Usage](#usage)
+ - [First step: choose your bundle profile](#first-step-choose-your-bundle-profile)
+ - [Details](#details)
+ - [Second step: Generate & install the core](#second-step-generate--install-the-core)
+ - [Third step: Generate & install your bundle](#third-step-generate--install-your-bundle)
+ - [Fourth step: Writing your first app](#fourth-step-writing-your-first-app)
+ - [Documentation](#documentation)
+- [Notes](#notes)
+ - [Python version](#python-version)
+ - [Directory structure](#directory-structure)
+ - [Troubleshooting](#troubleshooting)
+- [Running Unit Tests](#running-unit-tests)
+ - [Python](#python)
+ - [C++](#c)
-
-
-# YDK-GEN
+# Overview
- [](https://github.com/CiscoDevNet/ydk-gen/blob/master/LICENSE) [](https://travis-ci.org/CiscoDevNet/ydk-gen)
-[](https://codecov.io/gh/CiscoDevNet/ydk-gen)
-
-
-**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.
+**ydk-gen** is a developer tool that can generate API's that are modeled in YANG. Currently, it generates language binding for Python and C++ with planned support for other language bindings in the future.
Other tools and libraries are used to deliver `ydk-gen`'s functionality. In particular:
@@ -44,9 +49,9 @@ Of course, many other libraries are used as an integral part of ydk-gen and its
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
+# System requirements
-####Linux
+## Linux
Ubuntu (Debian-based): The following packages must be present in your system before installing YDK-Py:
```
$ sudo apt-get install python-pip zlib1g-dev python-lxml libxml2-dev libxslt1-dev python-dev libssh-dev libcurl4-openssl-dev libtool-bin libpcre3-dev libpcre++-dev libtool pkg-config python3-dev python3-lxml cmake clang
@@ -59,7 +64,7 @@ $ sudo yum install python-pip python-devel libxml2-devel libxslt-devel libssh-de
$ sudo ln -fs /usr/bin/cmake3 /usr/bin/cmake
```
-####Mac
+## macOS
It is recommended to install homebrew (http://brew.sh) and Xcode command line tools on your system before installing YDK-Py:
```
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
@@ -67,11 +72,11 @@ $ xcode-select --install
$ brew install pkg-config cmake libssh xml2 curl pcre
```
-####Windows
+## Windows
It is recommended to install a python distribution like [PythonXY](https://python-xy.github.io/) on your system before installing YDK-Py
-## Installation
-### Setting up your environment
+# Installation
+## Setting up your environment
We recommend that you run ydk-gen under a Python virtual environment (``virtualenv``/``virtualenvwrapper``). To install support in your system, execute
@@ -92,14 +97,14 @@ At this point, create a new virtual environment
```
$ mkvirtualenv -p python2.7 py2
```
-### Clone ydk-gen and install the requirements
+## Clone ydk-gen and install the requirements
```
$ git clone https://github.com/CiscoDevNet/ydk-gen.git
$ cd ydk-gen
$ pip install -r requirements.txt
```
-## Usage
+# Usage
```
$ ./generate.py --help
@@ -118,13 +123,13 @@ Options:
```
The below steps specify how to use `ydk-gen` to generate the core and a bundle. Pre-generated bundles and core are available for python and C++: [ydk-py](https://github.com/CiscoDevNet/ydk-py) and [ydk-cpp](https://github.com/CiscoDevNet/ydk-cpp).
-### First step: choose your bundle profile
+## First step: choose your bundle profile
The first step in using ydk-gen is either using one of the already existing [bundle profiles](https://github.com/CiscoDevNet/ydk-gen/tree/master/profiles/bundles) or constructing your own bundle profile, consisting of the YANG models you are interested in:
Construct a bundle profile file, such as [```ietf_0_1_1.json```](profiles/bundles/ietf_0_1_1.json) and specify its dependencies
-#### Details
+### Details
A sample bundle profile file is described below. The file is in a JSON format. Specify the `name` of your bundle, the `version` of the bundle and the `ydk_version`, which refers to [the version](https://github.com/CiscoDevNet/ydk-gen/releases) of the ydk core package you want to use with this bundle. The `name` of the bundle here is especially important as this will form part of the installation path of the bundle.
@@ -178,8 +183,8 @@ Only directory examples are shown below.
},
```
-### Second step: Generate & install the core
-
+## Second step: Generate & install the core
+
First, generate the core and install it:
For python:
@@ -193,13 +198,13 @@ For C++:
$ ./generate.py --cpp --core
$ cd gen-api/cpp/ydk/build && make && sudo make install
```
-
-### Third step: Generate & install your bundle
+
+## Third step: Generate & install your bundle
Then, generate your bundle using a bundle profile and install it:
For python:
```
-$ ./generate.py --python --bundle profiles/.json
+$ ./generate.py --python --bundle profiles/.json
$ pip install gen-api/python/-bundle/dist/ydk*.tar.gz
```
@@ -214,15 +219,15 @@ ydk-models- (0.5.1)
For C++:
```
-$ ./generate.py --cpp --bundle profiles/.json
+$ ./generate.py --cpp --bundle profiles/.json
$ cd gen-api/cpp/-bundle/build && make && make install
```
-### Fourth step: Writing your first app
+## Fourth step: Writing your first app
Now, you can start creating apps based on the models in your bundle. Assuming you generated a python bundle, the models will be available for importing in your app under `ydk.models.`. For examples, see [ydk-py-samples](https://github.com/CiscoDevNet/ydk-py-samples#a-hello-world-app) and [C++ samples](sdk/cpp/samples). Also refer to the [documentation for python](http://ydk.cisco.com/py/docs/developer_guide.html) and [for C++](http://ydk.cisco.com/cpp/docs/developer_guide.html).
-### Documentation
+## Documentation
When generating the YDK documentation for several bundles and the core, it is recommended to generate the bundles without the `--generate-doc` option. After generating all the bundles, the combined documentation for all the bundles and the core can be generated using the `--core --generate-doc` option. For example, the below sequence of commands will generate the documentation for the three python bundles and the python core (for C++, use `--cpp` instead of `--python`).
@@ -234,16 +239,16 @@ Note that the below process could take a few hours due to the size of the `cisco
./generate.py --python --bundle profiles/bundles/cisco_ios_xr_6_1_1.json
./generate.py --python --core --generate-doc
```
-Pre-generated documentation for [ydk-py](http://ydk.cisco.com/py/docs/) and [ydk-cpp](http://ydk.cisco.com/cpp/docs/) are available.
+Pre-generated documentation for [ydk-py](http://ydk.cisco.com/py/docs/) and [ydk-cpp](http://ydk.cisco.com/cpp/docs/) are available.
-## Notes
+# Notes
-### Python version
+## 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.
+- 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.
-### Directory structure
+## Directory structure
```
README - install and usage notes
@@ -259,7 +264,7 @@ sdk - sdk core and stubs for python and cpp
test - test code
```
-### Troubleshooting
+## Troubleshooting
Sometimes, developers using ydk-gen may run across errors when generating a YDK bundle using generate.py with some yang models. If there are issues with the .json profile file being used, such errors will be easily evident. Other times, when the problem is not so evident, it is recommended to try running with the `--verbose|-v` flag, which may reveal syntax problems with the yang models being used. For example,
```
@@ -272,9 +277,9 @@ cd /path/to/yang/models
pyang *.yang
```
-## Running Unit Tests
+# Running Unit Tests
-### Python
+## Python
First, generate and install the [test](profiles/test/ydktest.json) bundle and core package
```
$ ./generate.py --core
@@ -293,7 +298,7 @@ $ python test/test_sanity_levels.py
$ python test/test_sanity_filters.py
```
-### C++
+## C++
First, install the [test](profiles/test/ydktest-cpp.json) bundle and core package
```
$ ./generate.py --core --cpp
diff --git a/sdk/cpp/README.md b/sdk/cpp/README.md
index 8068ee048..e29da67c8 100644
--- a/sdk/cpp/README.md
+++ b/sdk/cpp/README.md
@@ -31,8 +31,8 @@ You can install YDK-Cpp on macOS or Linux. It is not currently supported on Win
Quick Install
-------------
-**macOS**
-You can install the latest model packages using [homebrew](http://brew.sh). It will manage the dependencies between YDK packages and all other sytem dependencies. First, add the third-party repository (homebrew tap) for YDK:
+**macOS**
+You can install the latest model packages using [homebrew](http://brew.sh). This utility will manage the dependencies between YDK packages and all other sytem dependencies. First, add the third-party repository (homebrew tap) for YDK:
```
$ brew tap CiscoDevNet/ydk
```
@@ -42,23 +42,23 @@ You get a fully operational YDK environment by installing the ``cisco-ios-xr`` b
$ brew install ydk-cisco-ios-xr
```
-Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute::
+Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute:
```
$ brew install ydk-openconfig
```
-If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute::
+If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute:
```
$ brew install ydk-ietf
```
-**Linux**
+**Linux**
Debian and RPM packages are coming soon. Currently, you have to install it from source (see below).
Installing from source
----------------------
### System Requirements
-**Linux**
+**Linux**
Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Cpp:
```
$ sudo apt-get install libcurl4-openssl-dev libpcre3-dev libssh-dev libxml2-dev libxslt1-dev libtool-bin cmake
@@ -70,8 +70,8 @@ $ sudo yum install epel-release
$ sudo yum install libxml2-devel libxslt-devel libssh-devel libtool gcc-c++ pcre-devel cmake
```
-**Mac**
-It is recommended to install homebrew (http://brew.sh) and Xcode command line tools on your system before installing YDK-Cpp
+**Mac**
+It is recommended to install [homebrew](http://brew.sh) and Xcode command line tools on your system before installing YDK-Cpp:
```
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install curl libssh pcre xml2 cmake
@@ -86,7 +86,7 @@ $ build$ cmake .. && make
$ build$ sudo make install
```
-Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are captured in the bundle packages used for quick installation. To install the IETF bundle, execute
+Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are captured in the bundle packages used for quick installation. To install the `ietf` bundle, execute:
```
$ core$ cd ../../ietf
$ ietf$ mkdir build && cd build
@@ -94,7 +94,7 @@ $ build$ cmake .. && make
$ build$ sudo make install
```
-To install the openconfig bundle, execute
+To install the `openconfig` bundle, execute:
```
$ ietf$ cd ../openconfig
$ openconfig$ mkdir build && cd build
@@ -102,7 +102,7 @@ $ build$ cmake .. && make
$ build$ sudo make install
```
-To install the cisco-ios-xr bundle, execute
+To install the `cisco-ios-xr` bundle, execute:
```
$ openconfig$ cd ../cisco-ios-xr
$ cisco-ios-xr$ mkdir build && cd build
@@ -112,11 +112,11 @@ $ build$ cd ../..
```
Documentation and Support
-===============
-- Samples can be found under the `core/samples` directory
-- API documentation can be found at http://ydk.cisco.com/cpp/docs
-- Additional samples can be found at https://github.com/CiscoDevNet/ydk-cpp-samples
-- For queries related to usage of the API, please join the YDK community at https://communities.cisco.com/community/developer/ydk
+=========================
+- Read the [API documentation](http://ydk.cisco.com/cpp/docs) for details on how to use the API and specific models
+- Samples can be found under the [samples directory](https://github.com/CiscoDevNet/ydk-cpp/tree/master/core/samples)
+- Additional samples can be found in the [YDK-Cpp samples repository](https://github.com/CiscoDevNet/ydk-cpp-samples)
+- Join the [YDK community](https://communities.cisco.com/community/developer/ydk) to connect with other users and with the makers of YDK
Release Notes
===============
diff --git a/sdk/cpp/core/docsgen/getting_started.rst b/sdk/cpp/core/docsgen/getting_started.rst
index 98f7e4ec9..5af7b791a 100644
--- a/sdk/cpp/core/docsgen/getting_started.rst
+++ b/sdk/cpp/core/docsgen/getting_started.rst
@@ -1,89 +1,105 @@
+===============
Getting Started
===============
.. contents:: Table of Contents
Overview
----------
+========
-The YANG Development Kit (YDK) is a Software Development Kit that provides API's that are modeled in YANG. The main goal of YDK is to reduce the learning curve of YANG data models by expressing the model semantics in an API and abstracting protocol/encoding details. YDK is composed of a core package that defines services and providers, plus one or more module bundles that are based on YANG models. Each module bundle is generated using a `bundle profile `_ and the `ydk-gen `_ tool.
+The YANG Development Kit (YDK) is a Software Development Kit that provides API's that are modeled in YANG. The main goal of YDK is to reduce the learning curve of YANG data models by expressing the model semantics in an API and abstracting protocol/encoding details. YDK is composed of a core package that defines services and providers, plus one or more module bundles that are based on YANG models.
-System Requirements
---------------------
-Linux
+How to Install
+==============
+You can install YDK-Cpp on macOS or Linux. It is not currently supported on Windows.
- Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Cpp::
-
+Quick Install
+-------------
+**macOS**
- $ sudo apt-get install libcurl4-openssl-dev libpcre3-dev libssh-dev libxml2-dev libxslt1-dev libtool-bin cmake
+You can install the latest model packages using `homebrew `_. This utility will manage the dependencies between YDK packages and all other sytem dependencies. First, add the third-party repository (homebrew tap) for YDK::
+ $ brew tap CiscoDevNet/ydk
- Centos (Fedora-based) - The following packages must be present in your system before installing YDK-Cpp::
+You get a fully operational YDK environment by installing the ``cisco-ios-xr`` bundle which automatically installs all other YDK-related packages (``ydk``, ``cisco-ios-xr``, ``openconfig`` and ``ietf`` packages)::
+ $ brew install ydk-cisco-ios-xr
- $ sudo yum install epel-release
- $ sudo yum install libxml2-devel libxslt-devel libssh-devel libtool gcc-c++ pcre-devel cmake
+Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute::
+ $ brew install ydk-openconfig
-Mac
+If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute::
- It is recommended to install homebrew (http://brew.sh) and Xcode command line tools on your system before installing YDK-Cpp::
-
+ $ brew install ydk-ietf
- $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- $ brew install curl libssh pcre xml2 cmake
- $ xcode-select --install
+**Linux**
+Debian and RPM packages are coming soon. Currently, you have to install it from source (see below).
-Windows
-
- YDK-Cpp is not currently supported on Windows
+Installing from source
+----------------------
+System Requirements
+~~~~~~~~~~~~~~~~~~~
+**Linux**
-Install Tips
--------------
-YDK uses ``cmake`` as the build system of choice. To install the ``core`` package::
+Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Cpp::
- ydk-cpp$ cd core/ydk
- ydk$ mkdir build && cd build
- build$ cmake .. && sudo make install
+ $ sudo apt-get install libcurl4-openssl-dev libpcre3-dev libssh-dev libxml2-dev libxslt1-dev libtool-bin cmake
-Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are already captured in the bundle package. To install the IETF bundle, execute::
+Centos (Fedora-based) - The following packages must be present in your system before installing YDK-Cpp::
- build$ cd ../../../ietf
- ietf$ mkdir build && cd build
- build$ cmake .. && sudo make install
+ $ sudo yum install epel-release
+ $ sudo yum install libxml2-devel libxslt-devel libssh-devel libtool gcc-c++ pcre-devel cmake
-To install the openconfig bundle, execute::
+**Mac**
- build$ cd ../../openconfig
- openconfig$ mkdir build && cd build
- build$ cmake .. && sudo make install
+It is recommended to install `homebrew `_ and Xcode command line tools on your system before installing YDK-Cpp::
-To install the cisco-ios-xr bundle, execute::
+ $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+ $ brew install curl libssh pcre xml2 cmake
+ $ xcode-select --install
- build$ cd ../../cisco-ios-xr
- cisco-ios-xr$ mkdir build && cd build
- build$ cmake .. && sudo make install
- build$ cd ../..
+Building YDK
+~~~~~~~~~~~~
+YDK uses ``cmake`` as the build system of choice. To install the ``core`` package, execute::
+ $ ydk-cpp$ cd core/ydk
+ $ core$ mkdir build && cd build
+ $ build$ cmake .. && make
+ $ build$ sudo make install
-Samples
--------------------
+Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are captured in the bundle packages used for quick installation. To install the ``ietf`` bundle, execute::
+
+ $ core$ cd ../../ietf
+ $ ietf$ mkdir build && cd build
+ $ build$ cmake .. && make
+ $ build$ sudo make install
+
+To install the ``openconfig`` bundle, execute::
-To get started with using the YDK API, there are sample apps available under the ``core/samples`` directory. For example, to run the ``core/samples/bgp_create.cpp`` sample, execute::
+ $ ietf$ cd ../openconfig
+ $ openconfig$ mkdir build && cd build
+ $ build$ cmake .. && make
+ $ build$ sudo make install
- ydk-cpp$ cd core/samples
- samples$ mkdir build && cd build
- build$ cmake .. && make
- build$ ./bgp_create ssh://:@: [-v]
+To install the ``cisco-ios-xr`` bundle, execute::
+ $ openconfig$ cd ../cisco-ios-xr
+ $ cisco-ios-xr$ mkdir build && cd build
+ $ build$ cmake .. && make
+ $ build$ sudo make install
+ $ build$ cd ../..
+
+Samples
+=======
+ To get started with using the YDK API, there are sample apps available in the `YDK-Cpp repository `_. For example, to run the ``bgp_create.cpp`` sample, execute::
-Release Notes
--------------------
-The current YDK release version is 0.5.4 (alpha). YDK-Cpp is licensed under the Apache 2.0 License.
+ ydk-cpp$ cd core/samples
+ samples$ mkdir build && cd build
+ build$ cmake .. && make
+ build$ ./bgp_create ssh://:@: [-v]
Documentation and Support
---------------------------
-- Samples can be found under the `core/samples `_ directory
-- API documentation can be found at http://ydk.cisco.com/cpp/docs
-- Additional samples can be found at https://github.com/CiscoDevNet/ydk-cpp-samples
-- For queries related to usage of the API, please join the YDK community at https://communities.cisco.com/community/developer/ydk
+=========================
+- Numerous additional samples can be found in the `YDK-Cpp samples repository `_
+- Join the `YDK community `_ to connect with other users and with the makers of YDK
diff --git a/sdk/python/README.rst b/sdk/python/README.rst
index b777f568e..720c90a1b 100644
--- a/sdk/python/README.rst
+++ b/sdk/python/README.rst
@@ -67,19 +67,19 @@ If you prefer not to use the YDK packages in the Python package index, you need
core$ python setup.py sdist
core$ pip install dist/ydk*.gz
-Once you have installed the ``ydk`` core package, you can install one more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are already captured in the bundle package. Make sure you install the desired bundles in the order below. To install the IETF bundle, execute::
+Once you have installed the ``ydk`` core package, you can install one more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are already captured in the bundle package. Make sure you install the desired bundles in the order below. To install the ``ietf`` bundle, execute::
core$ cd ../ietf
ietf$ python setup.py sdist
ietf$ pip install dist/ydk*.gz
-To install the OpenConfig bundle, execute::
+To install the ``openconfig`` bundle, execute::
ietf$ cd ../openconfig
openconfig$ python setup.py sdist
openconfig$ pip install dist/ydk*.gz
-To install the cisco-ios-xr bundle, execute::
+To install the ``cisco-ios-xr`` bundle, execute::
openconfig$ cd ../cisco-ios-xr
cisco-ios-xr$ python setup.py sdist
@@ -108,11 +108,10 @@ At this point, you can perform the quick install or the installation from source
Documentation and Support
--------------------------
-- Samples can be found under the ``core/samples`` directory
-- API documentation can be found at http://ydk.cisco.com/py/docs
-- Hundreds of samples can be found at https://github.com/CiscoDevNet/ydk-py-samples
-- For queries related to usage of the API, please join the YDK community at https://communities.cisco.com/community/developer/ydk
-
+- Read the `API documentation `_ for details on how to use the API and specific models
+- Samples can be found under the `samples directory `_
+- Hundreds of additional samples can be found in the `YDK-PY samples repository `_
+- Join the `YDK community `_ to connect with other users and with the makers of YDK
Release Notes
--------------
diff --git a/sdk/python/core/docsgen/getting_started.rst b/sdk/python/core/docsgen/getting_started.rst
index b83735be7..19fc98d28 100644
--- a/sdk/python/core/docsgen/getting_started.rst
+++ b/sdk/python/core/docsgen/getting_started.rst
@@ -1,82 +1,110 @@
+===============
Getting Started
===============
.. contents:: Table of Contents
Overview
---------
+========
-The YANG Development Kit (YDK) is a Software Development Kit that provides API's that are modeled in YANG. The main goal of YDK is to reduce the learning curve of YANG data models by expressing the model semantics in an API and abstracting protocol/encoding details. YDK is composed of a core package that defines services and providers, plus one or more module bundles that are based on YANG models. Each module bundle is generated using a `bundle profile `_ and the `ydk-gen `_ tool.
+The YANG Development Kit (YDK) is a Software Development Kit that provides API's that are modeled in YANG. The main goal of YDK is to reduce the learning curve of YANG data models by expressing the model semantics in an API and abstracting protocol/encoding details. YDK is composed of a core package that defines services and providers, plus one or more module bundles that are based on YANG models.
System Requirements
--------------------
+===================
Linux
- Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Py::
+-----
+Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Py::
+
+ $ sudo apt-get install python-pip zlib1g-dev python-lxml libxml2-dev libxslt1-dev python-dev
- $ sudo apt-get install python-pip zlib1g-dev python-lxml libxml2-dev libxslt1-dev python-dev
+Centos (Fedora-based) - The following packages must be present in your system before installing YDK-Py::
- Centos (Fedora-based) - The following packages must be present in your system before installing YDK-Py::
-
- $ sudo yum install epel-release
- $ sudo yum install python-pip python-devel libxml2-devel libxslt-devel libcurl-devel libtool
+ $ sudo yum install epel-release
+ $ sudo yum install python-pip python-devel libxml2-devel libxslt-devel libcurl-devel libtool
-Mac
- It is recommended to install homebrew (http://brew.sh), homebrew python package and Xcode command line tools on your system before installing YDK-Py::
+macOS
+-----
+It is required to install Xcode command line tools, `homebrew `_ and the following homebrew packages on your system before installing YDK-Py::
- $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- $ brew install python
- $ xcode-select --install
+ $ xcode-select --install
+ $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+ $ brew install python pkg-config libssh xml2 curl pcre
Windows
- It is recommended to install a python distribution like `PythonXY `_ on your system before installing YDK-Py
+-------
+You must install the following requirements::
+ * `Python Releases for Windows `_
+ * `Visual C++ Build Tools `_
Python Requirements
-~~~~~~~~~~~~
-Python2.7 or Python 3.4
+===================
+Both Python 2 and 3 are supported. At least, Python2.7 or Python 3.4 must be installed in your system.
+
+How to install
+==============
+Quick Install
+-------------
+You can install the latest model packages from the Python package index. Note that, in some systems, you need to install the new package as root. You get a fully operational YDK environment by installing the ``cisco-ios-xr`` bundle which automatically installs all other YDK-related packages (``ydk``, ``cisco-ios-xr``, ``openconfig`` and ``ietf`` packages)::
+
+ $ pip install ydk-models-cisco-ios-xr
+
+Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute::
+
+ $ pip install ydk-models-openconfig
-Install Tips
-------------
-We recommend that you perform the installation under a Python virtual environment (``virtualenv``/``virtualenvwrapper``). To install support in your system, execute::
+If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute::
- ydk-py$ pip install virtualenv virtualenvwrapper
- ydk-py$ source /usr/local/bin/virtualenvwrapper.sh
+ $ pip install ydk-models-ietf
-In some systems (e.g. Debian-based Linux), you may need to install support for Python virtual environments as root::
+Installing from Source
+----------------------
+If you prefer not to use the YDK packages in the Python package index, you need to install manually the ``ydk`` core package and then the model bundles you plan to use. To install the ``ydk`` core package, execute::
- ydk-py$ sudo pip install virtualenv virtualenvwrapper
- ydk-py$ source /usr/local/bin/virtualenvwrapper.sh
+ $ cd core
+ core$ python setup.py sdist
+ core$ pip install dist/ydk*.gz
-At this point, create a new virtual environment::
+Once you have installed the ``ydk`` core package, you can install one more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are already captured in the bundle package. Make sure you install the desired bundles in the order below. To install the ``ietf`` bundle, execute::
- ydk-py$ mkvirtualenv -p python2.7 ydk-py
+ core$ cd ../ietf
+ ietf$ python setup.py sdist
+ ietf$ pip install dist/ydk*.gz
-Now you can install the ``core`` package::
+To install the ``openconfig`` bundle, execute::
- (ydk-py)ydk-py$ cd core
- (ydk-py)core$ python setup.py sdist
- (ydk-py)core$ pip install dist/ydk*.gz
+ ietf$ cd ../openconfig
+ openconfig$ python setup.py sdist
+ openconfig$ pip install dist/ydk*.gz
-Once you have installed the ``core`` package, you can install one more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are already captured in the bundle package. To install the IETF bundle, execute::
+To install the ``cisco-ios-xr`` bundle, execute::
- (ydk-py)core$ cd ../ietf
- (ydk-py)ietf$ python setup.py sdist
- (ydk-py)ietf$ pip install dist/ydk*.gz
+ openconfig$ cd ../cisco-ios-xr
+ cisco-ios-xr$ python setup.py sdist
+ cisco-ios-xr$ pip install dist/ydk*.gz
+ cisco-ios-xr$ cd ..
-To install the OpenConfig bundle, execute::
+Using a Virtual Environment
+---------------------------
+You may want to perform the installation under a Python virtual environment (`virtualenv `_/`virtualenvwrapper `_). A virtual environment allows you to install multiple versions of YDK if needed. In addition, it prevents any potential conflicts between package dependencies in your system.
- (ydk-py)ietf$ cd ../openconfig
- (ydk-py)openconfig$ python setup.py sdist
- (ydk-py)openconfig$ pip install dist/ydk*.gz
+To install virtual environment support in your system, execute::
-To install the cisco-ios-xr bundle, execute::
+ $ pip install virtualenv virtualenvwrapper
+ $ source /usr/local/bin/virtualenvwrapper.sh
- (ydk-py)openconfig$ cd ../cisco-ios-xr
- (ydk-py)cisco-ios-xr$ python setup.py sdist
- (ydk-py)cisco-ios-xr$ pip install dist/ydk*.gz
- (ydk-py)cisco-ios-xr$ cd ..
+In some systems (e.g. Debian-based Linux), you need to install support for Python virtual environments as root::
+
+ $ sudo pip install virtualenv virtualenvwrapper
+ $ source /usr/local/bin/virtualenvwrapper.sh
+
+Create a new virtual environment::
+
+ $ mkvirtualenv -p python2.7 ydk-py
+
+At this point, you can perform the quick install or the installation from source described above. Take into account that must not attempt to install YDK as root under a virtual environment.
Samples
----------------
-To get started with using the YDK API, there are sample apps available under the ``core/samples`` directory. For example, to run the ``core/samples/bgp.py`` sample, execute::
+=======
+To get started with using the YDK API, there are sample apps available in the `YDK-Py repository `_. For example, to run the ``bgp.py`` sample, execute::
(ydk-py)ydk-py$ cd core/samples
(ydk-py)samples$ ./bgp.py -h
@@ -95,14 +123,7 @@ To get started with using the YDK API, there are sample apps available under the
(ydk-py)samples$ ./bgp.py --host -u -p --port
-
-Release Notes
---------------
-The current YDK release version is 0.5.4 (beta). YDK-Py is licensed under the Apache 2.0 License.
-
Documentation and Support
---------------------------
-- Samples can be found under the ``ydk-cpp/core/samples`` directory
-- API documentation can be found at http://ydk.cisco.com/py/docs
-- Additional samples can be found at https://github.com/CiscoDevNet/ydk-py-samples
-- For queries related to usage of the API, please join the YDK community at https://communities.cisco.com/community/developer/ydk
+=========================
+- Hundreds of samples can be found in the `YDK-Py samples repository `_
+- Join the `YDK community `_ to connect with other users and with the makers of YDK
diff --git a/ydkgen/__init__.py b/ydkgen/__init__.py
index 63df266f5..267674f92 100644
--- a/ydkgen/__init__.py
+++ b/ydkgen/__init__.py
@@ -320,7 +320,7 @@ def _modify_python_setup(gen_api_root, package_name, version, dependencies, desc
for line in fileinput.input(setup_file, inplace=True):
if not replaced_package and "$PACKAGE$" in line:
replaced_package = True
- print(line.replace("$PACKAGE$", package_name), end='')
+ print(line.replace("$PACKAGE$", package_name.replace('_', '-')), end='')
elif not replaced_version and "$VERSION$" in line:
replaced_version = True
print(line.replace("$VERSION$", version), end='')