The UML Designer’s web site is hosted on Github:
http://obeonetwork.github.io/UML-Designer/
The documentation source code is available on :
https://github.com/ObeoNetwork/UML-Designer/tree/master/documentation
The documentation build is on Travis :
https://travis-ci.org/ObeoNetwork/UML-Designer/
The documentation is built with Jekyll.
All the documentation is written with the textile syntax, in order that it is really easy to contribute.
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,
- title: New Page file: newpage---
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 :
h1(#MyAnchor). My title../path/MyPage.html#MyAnchorThe 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.
To test and generate the documentation locally, go to the folder containing the documentation content UML-Designer/documentation in the git repository.
Then launch :
jekyll build
and the Jekyll server to see the result of your contribution
jekyll serve
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 jekyll serve.
To build the documentation, commit and push the changes on the ObeoNetwork/UML-Designer master branch.
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.
The Travis build :
UML-Designer/documentation folder in your local repo.jekyll build_site folder containing all the .html files generated from the textile files.The new web site will be available immediately on : http://obeonetwork.github.io/UML-Designer/
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 UML-Designer/plugins/org.obeonetwork.dsl.uml2.design.doc/html.
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 :
UML-Modeling/plugins/org.obeonetwork.dsl.uml2.design.docbower installThis 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.