Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Intent/Getting Started

< Intent
Revision as of 05:09, 3 May 2013 by Alex.lagarde.obeo.fr (Talk | contribs) (Export documentation)

First example : synchronize Java code with Intent

General overview: What is Intent?

In a nutshell, Intent is a documentation environment providing tooling to:

  • efficiently write documentation within the Eclipse IDE
  • keep this documentation up-to-date by linking pieces of docs with technical artifacts (Java or C++ code, models, Manifests...)
  • export the documentation (in HTML, Latex, PDF...)

Create an Intent Project

  1. Open the Project Explorer view (Alt + Shift + Q / Q and select Project Explorer or Window > Show View... > Project Explorer)
  2. Open the Create New Wizard (Ctrl + N or right-click in the project explorer and select New..)
  3. Select the Intent Project Wizard and click _Next_
  4. Enter your Intent Project name (e.g. _"com.my.company.project.idoc"_), choose a working set (or leave to default). By clicking on Finish now, an empty Intent document will be created.
  5. If you select Next, you will be able to choose between a set of documentation templates. The *Standard Software Documentation Template* has been created to help you writing meaningful documentation. By clicking on Finish now, an Intent document initialized with the template you selected will be created

Actions available from an Intent project

Close the Intent editor thas has been automatically opened. Let's first focus on the Intent project in itself.

Open Intent editors

As you can see, an Intent project is structured as any documentation: it contains chapters, sections and sub-sections. Notice that you can open an Intent editor on any-sub part of the documentation, no matter how small. The idea is that you have above the eyes only the pieces of doc which are relevant in your current context, without having to handle an hundred of pages long document. Consequently, *we strongly advice you to open Intent editors on sub-parts of the doc* instead of the whole Intent document. To do so, simply double-click on an Intent element inside the project explorer view (e.g. the chapter _"1 Functional"_).

Now that the chapter 1 is opened, if you double-click on one of its sub-sections (e.g. _"1.6 Significant Scenarios"_, the sub-section will be selected inside the current editor. If you want to open a specific editor on this section, right-click on it and select the Open in a new Intent editor action.

Notice that there are other ways to open Intent editors (e.g. from the "Problem View":#Dealwithsynchronizationissues ), that will be detailed later in this guide.

Export documentation

By right-clicking on the Intent Project and selecting Export documentation as HTML, you will be able to export your Intent documentation as an HTML Bootstrap document.

Many other formats will soon be available, please do not hesitate to make requests on the Intent forum if you want a specific export format to be supported by Intent.

Write documentation with Intent

This section will show how you can use Intent to write _"traditional"_ documentation, i.e. explanations in natural language. As we will see "later":#LinkdocumentationJavacode , you will be able to *link pieces of this documentation with technical artifacts*.

You can customize the appearance of the Intent editor (line wrapping, bracket matching, colors...) by using the "Intent Preferences Page":#IntentPreferences .

Use the Intent Preview View

As explained "earlier":#OpenIntenteditors , open an Intent Editor on the Section 1.6 entitled _"Significant Scenarios"_.

Intent offers a real-time HTML preview of the documentation you are currently writing. You can access to this preview by:

  • selecting the _"Preview tab"_ at the bottom of your Intent editor
  • or opening the _"Intent Preview"_ View (Alt + Shift + Q / Q and select Intent Preview or Window > Show View... > Intent > Intent Preview)

This view can be useful to quickly make sure that the documentation you are writing is correctly rendered. It is refreshed any time you save an Intent editor or when you bring to top a new Intent editor.

Notice that you can disable this real-time preview mechanism from the "Intent Preferences Page":#Appearance , especially if you are dealing huge documents (live preview can impact Intent performances).

Create new sub-sections

From the 1.6 Section you have just opened, you can create a new sub-section by:

  • typing Section MyNewSubSection { some text }
  • use the completion (Ctrl + space) and select Section

Save your document, and you will see the new sub-section appear under the Intent project.

Write pure documentation

Intent uses the *Textile* syntax in pure documentation zones. For example, you can put a sentence in bold by using *sentence in bold*, insert images using !imgPath!, links by using "link text":http://linktarget... Use the completion (Ctrl + space) to see all available instructions.

Any textile effect will be rendered in the "Intent Preview View":#UsetheIntentPreviewView.

Please refer to the "Textile Syntax reference":../../../org.eclipse.mylyn.wikitext.help.ui/help/Textile-Syntax.html for further details about the textile syntax.

Link documentation & Java code

Drag and Drop technical artifacts

Open an Intent Editor on the Section 1.6 entitled _"Significant Scenarios"_. Let's write a new section presenting a functional scenario detailling a requirement of our system :

Now let's create a Java test to test the described scenario:

  • create a Java project entitled com.my.company.project.test
  • create a Java test inside this project containing a test method

To link this test method with the related piece of documentation, simply drop the method inside the Intent document. This drag & drop mechanism is extensible and works for any kind of technical artifact (Java files, model elements, MANIFEST files...).

You can see that a *reference* has been automatically created, and that an image showing the method and its javadoc is displayed inside the editor. Notice that this image rendering mechanism is extensible.

Use hyperlinks to navigate from documentation to code

Once the Intent editor is saved, your scenario in the documentation and the java test method become linked. By typing ctrl + click or F3 on the reference (*ref* instruction), you can open a Java editor on the corresponding artifact. Notice that this hyperlink mechanism is extensible.

Use the quick-outline to make semantic searches on your documentation

By typing ctrl + O, you can use the Intent *quick-outline* to query your documentation to get all the documentation parts related to some Java class, model element...

For example, if you type ctrl + O and search for *Test.java, you will get all the documentation parts related to a java test. The default scope of this search is the currently opened editor, but by typing ctrl + O again you will search through the whole Intent document.

Deal with synchronization issues

Now that you have linked a java method with a piece of documentation, any time you will modify this java method, Intent will display synchronization issues indicating the pieces of documentation that need to be updated.

Modify the method of your Scenario01 test (e.g. by adding a comment). You will see a *Synchronization warning* appear in the _Problems_ view and on the Intent project. From this warning, you can use the Intent > Show in Intent editor action to open an Intent editor on the documentation parts that needs to be updated.

You are free to update the outdated documentation parts whenever you want. It is up to you: *choose the most efficient way of updating documentation according to your process*. The Disciplined Agile Delivery describes several processes for updating your documentation: you may want to update it right away (“document continuously”), wait for the code to stabilize (e.g. the issue is closed), update the documentation just before a release (“document late”) or when people complain (“document only when it hurts”)...

Visualize differences

You can graphically visualize the differences between the documentation and the technical artifacts by:

  • clicking on a synchronization issue
  • typing Ctrl + 1 (or right-clicking and select Quick fix)
  • selecting the See all difference in compare editor action

A pop-up displaying all changes that occurred in the workspace and were not documented is opened, allowing you to determine how you should update your textual documentation.

Fix a synchronization issue

To fix a synchronization, first *update your textual documentation*, and :

  • click on the synchronization issue
  • type Ctrl + 1 (or right-clicking and select Quick fix)
  • select the Mark documentation as updated action
  • Save your Intent editor

The synchronization issue has now disappeared from your problem view, so now your documentation is up-to-date in regards to the changes you made on your software.

Intent Preferences

The Intent preference page (Window > Preferences > Mylyn > Intent) allows you to customize the behavior and appearance of Intent according to your own preferences.


Appearance

  • *Autowrap*: indicates whether the Intent editor should automatically wrap lines or not. Default value is true. If deactivated, then you will have horizontal scrollbars if a line length exceeds the editor size.
  • *Show HTML Preview page*: indicates whether the Intent editor should display a _'Preview'_ tab, and if the Intent Preview view should be refreshed in real time. Default value is true.
  • *Collapse Modeling Units*: indicates whether Modeling Units (\M M\ zones should be collapsed by default when opening a new Intent editor. Default value is false.
  • *Backets matching*: indicates whether Bracket matching should be activated on the Intent editor. Default value is true.

Colors

This preference tab allows you to customize the Intent editor appearance. Notice that you can also:

  • change the Font used by Intent to display Titles, Modeling Units & paragraphs through the General > Appearance > Colors and Fonts > Intent preference page
  • change the Intent annotations (synchronization & validation issues...) through the General > Editors > Text Editors > Annotations preference page

Export

  • *Display references inline*: indicates whether export should render ref instructions on a single line or not. Default value is false.

Other

  • *Activate back-up mechanism*: indicates whether the Intent document should be backed-up in an hidden ".intentbackup" file in the Intent project. Default value is false.
  • *Advanced logging*: this option is only used in debug, and makes each intent component (compiler, synchronizer...) log its activity.

Advanced use case: metamodel documentation

Authors William Piers
Contact william.piers@obeo.fr

Copyright 2011 Obeo.


Introduction

The aim of this tutorial is to get you started with Intent by helping you create your first Intent documentation project. For the purpose of this tutorial, we will create an Intent project which documents the concepts described by a metamodel.

Intent Getting started screenshot.png

Install Intent

Please check the Installation Guide to make sure you correctly install Intent.

Open the Project Explorer (if necessary)

An Intent project is meant to store a single documentation, it can be viewed as a documentation repository. To visualize this repository, you must use the Project Explorer view.

Intent Getting started project explorer view.png

If you cannot see this view in your current workbench - basically the project explorer is the default view under the Resource perspective, so if you are under another perspective you may not see this view - use the menu item Window > Show View > Project Explorer.

Intent Getting started project explorer selection.png

Create an Intent Project

In order to create a new Intent project, use the menu item File > New > Project > Intent Project.

Intent Getting started new intent project.png

Choose the name you want for your project (to stay consistent with the rest of the tutorial you can choose org.eclipse.intent.relational.idoc), then click Finish>.

Intent Getting started new intent project1.png

Note: a second wizard page is available to initialize the new documentation with existing content. There is no need to use it in this tutorial because we want to write a very simple document.

Intent Getting started new intent project2.png

Clicking on finish will create the project. You can now open the Intent document by double-clicking on the "Document" index in the project explorer view.

Intent Getting started new intent project result.png

Initialize the Metamodel Project

In this tutorial we are going to document a metamodel, while building it. To achieve this task we first need to create an empty EMF project which will contain the metamodel. Use the menu item File > New > Project > Empty EMF Project.

Intent Getting started metamodel.png

We are going to define a "relational" metamodel which describes databases, so you can name the project org.eclipse.intent.relational. Click Finish>.

Intent Getting started metamodel2.png

The Intent editor

The Intent editor provides the following features:

  • Syntax highlighting
  • Content assistant (ctrl + space)
  • Error detection
  • Quick fixes (ctrl + shift + 1)
  • Dynamic outline
  • Quick outline (ctrl + O)
Intent editor screenshot

Writing the documentation

Now in the newly created document we can describe the metamodel goal. To structure the content of the document we can use a few structural concepts:

  • Document: the root of the intent document. There can be only one document per repository. A document contains Chapters.
  • Chapter: The sub parts of a document. Contains text, sections.
  • Section: The sub parts of a chapter. Contains text, sections and Modeling Units.
  • Modeling Units: Can only be contained by a section. Describes parts of an observed resource in order to synchronize it with the real world.

Using those contexts you can start to write the documentation:

Document {
    Chapter  The relational metamodel {    
        This chapter describes the relational metamodel.
 
        Section The relational package {             
            This section describes the concepts of the relational package, which is the *main* package of the relational metamodel.
 
        }
    }
}

All of the text parts can use the textile constructs, such as bold (*bold text*), italic and so on.

Describing the metamodel

In this part we are going to define the metamodel content and synchronize the intent document with the real world.

Initialize the metamodel content

The modeling unit syntax allow to split the metamodel content definition in several locations in the document. This way you can easily document each concern of the metamodel in different sections.

We can add a modeling unit to the first section:

Section   The relational package {
    This section describes the concepts of the relational package, which is the *main* package of the relational metamodel.
            
    @M
        new EPackage relational {
            nsURI = "http://www.eclipse.org/intent/relational";
            nsPrefix = "relational";
        }
    M@
}

This modeling unit defines an EPackage named relational. Notice that the first word after the type (EPackage) is assumed by the Intent compiler to be the name of the instance.

An alternative syntax to this declaration is :

new EPackage {
    name = "relational";
    nsURI = "http://www.eclipse.org/intent/relational";
    nsPrefix = "relational";
}

Inside of this declaration we set the required fields, nsURI and prefix.

When saving the document, no error are detected as the EPackage is not yet synchronized with an actual resource.

Synchronization with the real world

To achieve the synchronization between the metamodel we describe and the real world (Working Copy), we need to define a Resource, which will symbolize the metamodel file that we want to keep synchronization with.

You can declare the resource in a separate section if you want:

Section The metamodel resource {
    The metamodel resource is defined under the 'model' folder of the metamodel plugin.

    @M
        Resource relationalResource {
	     URI = "platform:/resource/org.eclipse.intent.relational/model/relational.ecore";
	     content += relational;
 	 }
    M@
}

In the resource declaration you have to set two fields:

  • URI : Allows to set (=) the location of the actual resource to synchronize with the document. Here we define that the metamodel (relational.ecore) is located inside of the model folder of the org.eclipse.intent.relational plugin found in the workspace (platform:/resource).
URI = "platform:/resource/org.eclipse.intent.relational/model/relational.ecore";
  • content : Allows to add content to the resource. Here we add (+=) the previously defined relational EPackage.
content += relational;

When saving the document, the Synchronizer detects that the resource does not exists.

Intent Getting started null resource.png

You can directly create the metamodel by applying the quick fix (Right-click on the error> Quick Fix > press Enter). From now on you will be able to define the metamodel content in the document through modeling units and synchronize the actual resource using the quickfixes, by applying differences from the document to the actual resource.

Contribute to the metamodel content

Now you can contribute content to your metamodel when writing the documentation, regularly synchronizing the actual resource using the quick fixes.

Below are some samples of modeling unit that can be contributed in any order inside of the intent document.

  • A NamedElement superclass, which can be added to the The relational package Section :
@M
    relational {
        eClassifiers += new EClass NamedElement {
            abstract = "true";
            eStructuralFeatures += new EAttribute {
                name = "name";
                eType = String;
            };
        };
    }
M@

In this modeling unit we use an inline declaration for the name EAttribute, using the new instruction.

The new element is detected by Intent as a synchronization warning, as it is not defined into the actual metamodel (the relational.ecore file).

Intent Getting started sync warning.png

We now want to transfer the definition we made in the document to the actual file. To achieve this, you can right click on this warning, and click on Quick fix. This will give the following dialog:

Intent Getting started sync fix.png

If you double click - or type enter - on the proposed quick fix, it will open a dialog showing a comparison between the real world resource (the "working copy") and the intent document resource.

Intent Getting started sync compare.png

Using this dialog you can apply changes from left to right using the top right arrows, and finally click on Commit to save the applied changes. If you apply all the changes it will make the document synchronization warning disappear.

You can proceed like this for all the further elements.

  • A Database concept :
Section The database concept {
    This concept symbolizes a database and allows to store schemas.

    @M
        relational {
            eClassifiers += new EClass Database {
                 eSuperTypes += NamedElement;
                 eStructuralFeatures += new EReference {
                     name = "ownedSchemas";
                     eType = DBSchema;
                     containment = "true";
                 };
             };
        }
    M@        
}

In this modeling unit there are two references to other modeling units: eSuperTypes refers to the previously declared NamedElement and ownedSchemas refers to a DBSchema concept.

There is no need to declare NamedElement before Database to allow Database to use it.

As no DBSchema has not be defined yet, the Compiler detects the following error, which will be gone once the DBSchema concept will be defined.

Intent Getting started type not found.png
  • Below are the definitions of some other concepts of the metamodel. You can try to write them by you own and use this as a reference:
@M
    relational {
        eClassifiers += new EClass DBSchema {
            eSuperTypes += NamedElement;
            eStructuralFeatures += new EReference {
                name = "ownedTables";
                eType = DBTable;
                upperBound = "-1";
                containment = "true";
            };
        };
        eClassifiers += new EClass DBTable {
            eSuperTypes += NamedElement;
            eStructuralFeatures += new EReference {
                name = "ownedColumns";
                eType = DBColumn;
                upperBound = "-1";
                containment = "true";
            };
        };
        eClassifiers += new EClass DBColumn {
            eSuperTypes += NamedElement;
            eStructuralFeatures += new EAttribute {
                name = "type";
                eType = DBDataType;
            };
        };
        eClassifiers += new EEnum DBDataType {
            eLiterals += new EEnumLiteral {
                name = "VARCHAR";
                literal = "VARCHAR";
                value = "0";
            };
            eLiterals += new EEnumLiteral {
                name = "NUMBER";
                literal = "NUMBER";
                value = "1";
            };
        };
    }
M@

Following evolutions using Intent's synchronizer

Now we can use the couple document/metamodel kept in synchronization by intent in situation.

For instance, an user of the relational metamodel found that he wants to put several schemas into a database, which sounds legit. So he opens the metamodel file, changes the upperBound attribute of the Database EClass to "-1" in order to make it multiple.

Intent Getting started metamodel change.png

When reopening the database section, Intent has detected the desynchronization:

Intent Getting started metamodel change error.png

The following actions are up to you, as Intent is just a way to point any desynchronization issues: so you can either modify the document and the associated text description to match the change, or revert the metamodel modification made by the user because it doesn't match your requirements.

Intent Getting started doc fixed.png

Back to the top