-== YangIDE User Guide
-Refer to this template to identify the required sections and information
-that you should provide for a User Guide. The user guide should contain
-configuration, administration, management, using, and troubleshooting
-sections for the feature.
+== YANG IDE User Guide
=== Overview
-Provide an overview of the feature and the use case. Also include the
-audience who will use the feature. For example, audience can be the
-network administrator, cloud administrator, network engineer, system
-administrators, and so on.
-
-=== YangIDE Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help.
-
-=== Configuring YangIDE
-
-Describe how to configure the feature or the project after installation.
-Configuration information could include day-one activities for a project
-such as configuring users, configuring clients/servers and so on.
-
-=== Administering or Managing YangIDE
-Include related command reference or operations that you could perform
-using the feature. For example viewing network statistics, monitoring
-the network, generating reports, and so on.
-
-NOTE: Ensure that you create a step procedure whenever required and
-avoid concepts.
-
-For example:
-
-.To configure L2switch components perform the following steps.
-. Step 1:
-. Step 2:
-. Step 3:
-
-=== Tutorials
-<optional>
-If there is only one tutorial, you skip the "Tutorials" section and
-instead just lead with the single tutorial's name.
-
-==== <Tutorial Name>
-Ensure that the title starts with a gerund. For example using,
-monitoring, creating, and so on.
-
-===== Overview
-An overview of the use case.
-
-===== Prerequisites
-Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-Include any topology requirement for the use case. Ideally, provide
-visual (abstract) layout of network diagrams and any other useful visual
-aides.
-
-===== Instructions
-Use case could be a set of configuration procedures. Including
-screenshots to help demonstrate what is happening is especially useful.
-Ensure that you specify them separately. For example:
-
-. *Setting up the VM*
-To set up a VM perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Installing the feature*
-To install the feature perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
-
-. *Configuring the environment*
-To configure the system perform the following steps.
-.. Step 1
-.. Step 2
-.. Step 3
+
+The YANG IDE project provides an Eclipse plugin that is used to create,
+view, and edit Yang model files. It currently supports version 1.0 of
+the Yang specification.
+
+The YANG IDE project uses components from the OpenDaylight project for
+parsing and verifying Yang model files. The "yangtools" parser in
+OpenDaylight is generally used for generating Java code associated
+with Yang models. If you are just using the YANG IDE to view and edit
+Yang models, you do not need to know any more about this.
+
+Although the YANG IDE plugin is used in Eclipse, it is not necessary to
+be familiar with the Java programming language to use it effectively.
+
+The YANG IDE also uses the Maven build tool, but you do not have to be
+a Maven expert to use it, or even know that much about it. Very
+little configuration of Maven files will have to be done by you. In
+fact, about the only thing you will likely ever need to change can be
+done entirely in the Eclipse GUI forms, without even seeing the
+internal structure of the Maven POM file (Project Object Model).
+
+The YANG IDE plugin provides features that are similar to other
+programming language plugins in the Eclipse ecosystem.
+
+For instance, you will find support for the following:
+
+* Immediate "as-you-type" display of syntactic and semantic errors
+* Intelligent completion of language tokens, limited to only choices
+valid in the current scope and namespace
+* Consistent (and customizable) color-coding of syntactic and semantic symbols
+* Provides access to remote Yang models by specifying dependency on
+Maven artifact containing models (or by manual inclusion in project)
+* One-click navigation to referenced symbols in external files
+* Mouse hovers display descriptions of referenced components
+* Tools for refactoring or renaming components respect namespaces
+* Code templates can be entered for common conventions
+
+Forthcoming sections of this manual will step through how to utilize
+these features.
+
+=== Creating a Yang Project
+
+After the plugin is installed, the next thing you have to do is create
+a Yang Project. This is done from the "File" menu, selecting "New",
+and navigating to the "Yang" section and selecting "YANG Project", and
+then clicking "Next" for more items to configure.
+
+Some shortcuts for these steps are the following:
+
+* Typically, the key sequence "Ctrl+n" (press "n" while holding down
+one of the "ctrl" keys) is bound to the "new" function
+* In the "New" wizard dialog, the initial focus is in the filter
+field, where you can enter "yang" to limit the choices to only the
+functions provided by the YANG IDE plugin
+* On the "New" wizard dialog, instead of clicking the "Next" button
+with your mouse, you can press "Alt+n" (you will see a hint for this
+with the "N" being underlined)
+
+==== First Yang Project Wizard Page
+
+After the "Next" button is pressed, it goes to the first wizard page
+that is specific to creating Yang projects. you will see a subtitle on
+this page of "YANG Tools Configuration". In almost all cases, you
+should be able to click "Next" again on this page to go to the next
+wizard page.
+
+However, some information about the fields on this page would be helpful.
+
+You will see the following labeled fields and sections:
+
+===== Yang Files Root Directory
+
+This defaults to "src/main/yang". Except when creating your first
+Yang file, you, you do not even have to know this, as Eclipse presents
+the same interface to view your Yang files no matter what you set
+this to.
+
+===== Source Code Generators
+
+If you do not know what this is, you do not need to know about it. The
+"yangtools" Yang parser from OpenDaylight uses a "code generator"
+component to generate specific kinds of Java classes from the Yang
+models. Again, if you do not need to work with the generated Java
+code, you do not need to change this.
+
+===== Create Example YANG File
+
+This is likely the only field you will ever have any reason to change.
+If this checkbox is set, when the YANG IDE creates the Yang project,
+it will create a sample "acme-system.yang" file which you can view and
+edit to demonstrate the features of the tool to yourself. If you
+do not need this file, then either delete it from the project or
+uncheck the checkbox to prevent its creation.
+
+When done with the fields on this page, click the "Next" button to go
+to the next wizard page.
+
+==== Second Yang Project Wizard Page
+
+This page has a subtitle of "New Maven project". There are several
+fields on this page, but you will only ever have to see and change the
+setting of the first field, the "Create a simple project" checkbox.
+You should always set this ON to avoid the selection of a Maven
+archetype, which is something you do not need to do for creating a
+Yang project.
+
+Click "Next" at the bottom of the page to move to the next wizard page.
+
+==== Third Yang Project Wizard Page
+
+This also has a subtitle of "New Maven project", but with different
+fields to set. You will likely only ever set the first two fields,
+and completely ignore everything else.
+
+The first field is labeled "Group id" in the "Artifact" section. It
+really does not matter what you set this to, but it does have to be set
+to something. For consistency, you might set this to the name or
+nickname of your organization. Otherwise, there are no constraints on
+the value of this field.
+
+The second field is labeled "Artifact id". The value of this field
+will be used as the name of the project you create, so you will have
+to think about what you want the project to be called. Also note that
+this name has to be unique in the Eclipse workspace. You cannot have
+two projects with the same name.
+
+After you have set this field, you will notice that the "Next" button is
+insensitive, but now the "Finish" button is sensitive. You can click
+"Finish" now (or use the keyboard shortcut of "Alt+f"), and the Yang
+IDE will finally create your project.
+
+=== Creating a Yang File
+
+Now that you have created your project, it is time to create your first Yang file.
+
+When you created the Yang project, you might have noticed the other
+option next to "YANG Project", which was "YANG File". That is what
+you will select now. Click "Next" to go to the first wizard page.
+
+==== First Yang File Wizard Page
+
+This wizard page lets you specify where the new file will be located, and its name.
+
+You have to select the particular project you want the file to go
+into, and it needs to go into the "src/main/yang" folder (or a
+different location if you changed that field when creating the
+project).
+
+You then enter the desired name of the file in the "File name". The
+file name should have no spaces or "special characters" in it. You
+can specify a ".yang" extent if you want. If you do not specify an
+extent, the YANG IDE will create it with the ".yang" extent.
+
+Click "Next" to go to the next wizard page.
+
+==== Second Yang File Wizard Page
+
+On this wizard page, you set some metadata about the module that is
+used to initialize the contents of the Yang file.
+
+It has the following fields:
+
+===== Module Name
+
+This will default to the "base name" of the file name you created.
+For instance, if the file name you created was "network-setup.yang",
+this field will default to "network-setup". You should leave this
+value as is. There is no good reason to define a model with a name
+different from the file name.
+
+===== Namespace
+
+This defaults to "urn:opendaylight:xxx", where "xxx" is the "base
+name" of the file name you created. You should put a lot of thought
+into designing a namespace naming scheme that is used throughout your
+organization. It is quite common for this namespace value to look like
+a "http" URL, but note that that is just a convention, and will not
+necessarily imply that there is a web page residing at that HTTP
+address.
+
+===== Prefix
+
+This defaults to the "base name" of the file name you created. It
+mostly does not technically matter what you set this to, as long as
+it is not empty. Conventionally, it should be a "nickname" that is
+used to refer to the given namespace in an abbreviated form, when
+referenced in an "import" statement in another Yang model file.
+
+===== Revision
+
+This has to be a date value in the form of "yyyy-mm-dd", representing
+the last modified date of this Yang model. The value will default to
+the current date.
+
+===== Revision Description
+
+This is just human-readable text, which will go into the "description"
+field underneath the Yang "revision" field, which will describe what
+went into this revision.
+
+When all the fields have the content you want, click the "Finish"
+button to set the YANG IDE create the file in the specified location.
+It will then present the new file in the editor view for additional
+modifications.
+
+=== Accessing Artifacts for Yang Model Imports
+
+You might be working on Yang models that are "abstract" or are
+intended to be imported by other Yang models. You might also, and
+more likely, be working on Yang models that import other "abstract"
+Yang models.
+
+Assuming you are in that latter more common group, you need to consider
+for yourself, and for your organization, how you are going to get
+access to those models that you import.
+
+You could use a very simple and primitive approach of somehow
+obtaining those models from some source as plain files and just
+copying them into the "src/main/yang" folder of your project. For a
+simple demo or a "one-off" very short project, that might be
+sufficient.
+
+A more robust and maintainable approach would be to reference
+"coordinates" of the artifacts containing Yang models to import. When
+you specify unique coordinates associated with that artifact, the Yang
+IDE can retrieve the artifact in the background and make it available
+for your "import" statements.
+
+Those "coordinates" that I speak of refer to the Maven concepts of
+"group id", "artifact id", and "version". you may remember "group id"
+and "artifact id" from the wizard page for creating a Yang project.
+It is the same idea. If you ever produce Yang model artifacts that
+other people are going to import, you will want to think more about what
+you set those values to when you created the project.
+
+For example, the OpenDaylight project produces several importable
+artifacts that you can specify to get access to common Yang models.
+
+==== Turning on Indexing for Maven Repositories
+
+Before we talk about how to add dependencies to Maven artifacts with
+Yang models for import, I need to explain how to make it easier to
+find those artifacts.
+
+In the Yang project that you have created, the "pom.xml" file (also
+called a "POM file") is the file that Maven uses to specify
+dependencies. We will talk about that in a minute, but first we need to
+talk about "repositories". These are where artifacts are stored.
+
+We are going to have Eclipse show us the "Maven Repositories" view.
+In the main menu, select "Window" and then "Show View", and then
+"Other". Like in the "New" dialog, you can enter "maven" in the
+filter field to limit the list to views with "maven" in the name.
+Click on the "Maven Repositories" entry and click OK.
+
+This will usually create the view in the bottom panel of the window.
+
+The view presents an outline view of four principal elements:
+
+* Local Repositories
+* Global Repositories
+* Project Repositories
+* Custom Repositories
+
+For this purpose, the only section you care about is "Project
+Repositories", being the repositories that are only specified in the
+POM for the project. There should be a "right-pointing arrow" icon on
+the line. Click that to expand the entry.
+
+You should see two entries there:
+
+* opendaylight-release
+* opendaylight-snapshot
+
+You will also see internet URLs associated with each of those repositories.
+
+For this purpose, you only care about the first one. Right-click on
+that entry and select "Full Index Enabled". The first time you do
+this on the first project you create, it will spend several minutes
+walking the entire tree of artifacts available at that repository and
+"indexing" all of those components. When this is done, searching for
+available artifacts in that repository will go very quickly.
+
+=== Adding Dependencies Containing Yang Models
+
+Double-click the "pom.xml" file in your project. Instead of just
+bringing up the view of an XML file (although you can see that if you
+like), it presents a GUI form editor with a handful of tabs.
+
+The first tab, "Overview", shows things like the "Group Id", "Artifact
+Id", and "Version", which represents the "Maven coordinate" of your
+project, which I have mentioned before.
+
+Now click on the "Dependencies" tab. You will now see two list
+components, labeled "Dependencies" and "Dependency Management". You
+only care about the "Dependencies" section.
+
+In the "Dependencies" section, you should see one dependency for an
+artifact called "yang-binding". This artifact is part of
+OpenDaylight, but you do not need to know anything about it.
+
+Now click the "Add" button.
+
+This brings up a dialog titled "Select Dependency". It has three
+fields at the top labeled "Group Id", "Artifact Id", and "Version",
+with a "Scope" dropdown. You will never have a need to change the
+"Scope" dropdown, so ignore it. Despite the fact that you will need to
+get values into these fields, in general usage, you will never have to
+manually enter values into them, but you will see values being inserted
+into these fields by the next steps I describe.
+
+Below those fields is a field labeled "Enter groupId, artifactId ...".
+This is effectively a "filter field", like on the "New" dialog, but
+instead of limiting the list from a short list of choices, the value
+you enter there will be matched against all of the artifacts that were
+indexed in the "opendaylight-release" repository (and others). It
+will match the string you enter as a substring of any groupId or
+artifactId.
+
+For all of the entries that match that substring, it will list an
+entry showing the groupId and artifactId, with an expansion arrow. If
+you open it by clicking on the arrow, you will see individual entries
+corresponding to each available version of that artifact, along with
+some metadata about the artifacts between square brackets, mostly
+indicating what "type" of artifact is.
+
+For your purposes, you only ever want to use "bundle" or "jar" artifacts.
+
+Let us consider an example that many people will probably be using.
+
+In the filter field, enter "ietf-yang-types". Depending on what
+versions are available, you should see a small handful of "groupId,
+artifactId" entries there. One of them should be groupId
+"org.opendaylight.mdsal.model" and artifactId "ietf-yang-types".
+Click on the expansion arrow to open that.
+
+What you will see at this point depends on what versions are
+available. You will likely want to select the newest one (most likely
+top of the list) that is also either a "bundle" or "jar" type
+artifact.
+
+If you click on that resulting version entry, you should notice at
+this point that the "Group Id", "Artifact Id", and "Version" fields at
+the top of the dialog are now filled in with the values corresponding
+to this artifact and version.
+
+If this is the version that you want, click OK and this artifact will
+be added to the dependencies in the POM.
+
+This will now make the Yang models found in that artifact available in
+"import" statements in Yang models, not to mention the completion
+choices for that "import" statement.
Code Review / docs.git / commitdiff