Documentation developer guide
The UML Designer’s web site is hosted on Github: http://www.umldesigner.org/
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/
Environment
The documentation is built with Jekyll.
All the documentation is written with the markdown 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: 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 :
Have a look the section below to see how to define an anchor in a page.
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:
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 markdown syntax.
Use the following syntax to :
- Define an anchor in the page named MyPage and defined in the folder path :
# My title
- Reference an anchor :
../path/MyPage.html#my-title
Layouts
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 (750x500 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 (900x300 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
Locally
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
.
Continuous integration
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.
- it is also 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/documentation
folder in your local repo. - And launch :
jekyll build
This operation will generate a new_site
folder containing all the.html
files 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 Travis 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 :
- go to
UML-Modeling/plugins/org.obeonetwork.dsl.uml2.design.doc
- launch
bower install
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.