Documentation developer guide
The UML Designer’s web site is hosted on Github:
The documentation source code is available on :
The documentation build is on Travis :
The documentation is built with Jekyll.
All the documentation is written with the textile syntax, in order that it is really easy to contribute.
Structure of the documentation
In a Jekyll-powered website, there are two basic kinds of resources, pages and posts. Both of those resources can be made visible on the navigation bar by modifying the file in _data/pages.yml. If you want to create a top level link, add a “page” with the path of its “file” (without the extension). If you want to add a top level menu with submenus, add a “category” and child “pages” with their “title” and “file”. Then you just have to create your file in textile.
- title: Overview file: overview - title: Download file: download - category: Tutorials pages: - title: Getting started file: tutorials/tuto-getting-started - title: Create project file: tutorials/tuto-create-project ...
- title: xxx and
- category: xxx generate a menu in the main web site navbar.
To create a menu which reference an anchor in an existing page use the syntax :
- category: MyCategory pages: - title: MyTitle file: path/filename anchor: MyAnchor
Have a look the section below to see how to define an anchor in a page.
When you create a page, you don’t need to create the whole file manually, you can just reuse existing components automatically. For example, in order to create a very basic page,
- Modify the file pages.yml to add the following content:
- title: New Page file: newpage
- Use the following piece of code in a file named newpage.textile at the root of the documentation project:
--- layout: page title: New Page subtitle: New Sub Title relativePath: .. --- Hello World in textile
This allows to set the different variables.
All the pages reused the same includes : https://github.com/ObeoNetwork/UML-Designer/tree/master/documentation/_includes
The rest of the page, defines the main content.
This textile page will be converted automatically in html. By indicating that you want to reuse the page layout, you will also have a header, a footer, the navigation bar etc. You only have to worry about your content.
To edit the page content use the textile syntax.
Use the following syntax to :
- Define an anchor in the page named MyPage and defined in the folder path :
h1(#MyAnchor). My title
- Reference an anchor :
The available layouts are defined in the _layouts folder.
There are several layout already available for the documentation. Those layouts may contain variables used to display some content in the page.
- page, a basic page with the navigation bar, header, footer.
- title: the title of the page
- article, a full width article with its breadcrumb (it extends the page layout)
- subtitle: subtitle
- article-with-image, an article with an image (it extends the page layout)
- image: A large image (750×500 px) illustrating the article
- description: Description of the image
- article-with-sidebar, used for tutorials (it extends the page layout)
- category: the name of the category of elements from the navigation bar to display in the sidebar
- blog-post, used for blog posts (it extends the page layout)
- author: The author of the post
- date: The date of the post, using the following format: YYYY-MM-DD HH:MM:SS
- image (optional): A wide image (900×300 pixel) illustrating the post
- excerpt (optional): A paragraph describing the article. It will be used in the page listing all the posts instead of the whole content of the post.
- lead (optional): An introduction paragraph which will be highlighted at the top of the post.
Build the documentation
To test and generate the documentation locally, go to the folder containing the documentation content
UML-Designer/documentation in the git repository.
Then launch :
and the Jekyll server to see the result of your contribution
The documentation will be available at
localhost:4000/index.html. Use a web browser and go to this URL to browse the documentation. If you want to iterate and try new changes, modify the documentation then stop the
jekyll serve by using
Ctrl+C and relaunch it using
To build the documentation, commit and push the changes on the ObeoNetwork/UML-Designer
The Travis build is launched, it generates the documentation and updates the gh-pages. Consequently, the web site is updated automatically.
The Hudson build is in charge of the integration of the web site inside the Eclipse Help Content.
The different steps done by the builds are explained below.
Build the web-site
The Travis build :
- Go to
UML-Designer/documentationfolder in your local repo.
- And launch :
This operation will generate a new
_sitefolder containing all the
.htmlfiles generated from the textile files.
- To update the online web-site, just copy/paste the content of the _site folder to the gh-pages branch on the repo. Commit and push the new version of the web-site.
The new web site will be available immediately on : http://www.umldesigner.org/
Integrate the documentation to Eclipse
The web site is integrated inside Eclipse as embedded documentation for UML Designer. This is done by the Hudson build which takes the gh-pages content and integrates it into the Eclipse Help Content. The content of the
gh-pages is just copied to
Pay attention when you update the documentation structure to update also the Eclipse toc. We defined an Eclipse specific toc.xml file which is used to integrate the web site content into the Eclipse Help Content table of content.
When a change is done in the documentation, the Travis build runs after the commit of the change. If you want to see this documentation update also in the Eclipse documentation, the Hudson build must be run manually after the end of the Travis build.
To test the Eclipse documentation integration locally :
- go to
This action uses the bower.json and .bowerrc files defined in the org.obeonetwork.dsl.uml2.design.doc to retrieve the documentation content from the online gh-pages to the local html folder.