Documentation revamp

As another big improvement to Ontopia comes close to being finished we want to share a sneak peek with you all.

The original idea to revamp the documentation was presented in Juni of 2015 as an enhancement to move from docbook to markdown. The main reasons for moving to markdown are:

  • Integrates better with Github by displaying markdown files as HTML, as seen here.
  • Makes the documentation source files easier to read and edit by reducing markup.
  • Removes the need for an unstable docbook plugin
  • Removes the need for Ant tasks to move files around

With the help of some automation the docbooks where converted to Markdown in march 2016. From this work it became clear that a new documentation style was required to come to an acceptable result. We’ve only recently been able to finish this part of the work. The final piece was to make sure that the distribution and all modules had the correct documentation pages and resources.

Features of the new documentation include:

  • Based on Twitter’s Bootstrap style, modified to an Ontopia color scheme
  • The documentation index is now available as a menu in every page (except javadoc)
  • Mobile device support

The near-finished code has been pushed to Github in the ‘feature/markdown’ branch pending review. The new documentation has been uploaded to a temporary location so you may preview it live:

http://ontopia.mssm.nl/doc/5.3.1/

We welcome comments and suggestions on these changes, please use the mailing list to let us know what you think of it.

Screenshots:

documentation
Documentation style
documentation-mobile
Mobile ready
Advertisements

Introducing Ontopia REST

It is with great joy that we announce a new addition to the Ontopia framework: Ontopia REST. This new module aims to provide a complete REST implementation for core Ontopia functionality. The module is loosely based on the work David Damen did in the Tropics sandbox project. As such it also uses the well known and often used Restlet Java framework.

Goal

The goal of this new module is two-fold:

  • To provide developers new ways to use the power of Ontopia, without the need for in-depth knowledge of the full Ontopia code
  • To work towards replacing deprecated and antiquated modules such as
    • Webeditor framework
    • TMRAP
    • Vizigator
    • Navigator framework
    • Omnigator

Where the first goal requires only an Ontopia release to realize, the second goal will be an undertaking of its own.

Functionality

A short summary of functionality included:

  • Getting, adding, changing and removing all Topic Map constructs
  • Communication mainly focussed on JSON, by leveraging Jackson
  • XTM, CTM, LTM and TMXML exposing of full Topic Map
  • XTM and TMXML exposing of topic fragments
  • Paging on collection requests
  • Exposing methods in indexes such as ClassInstanceIndexIF and SearcherIF

Status

The module that was added to the Ontopia source contains a big part of the functionality envisioned. A large test suite has been set up to cover all the implemented functionality, containing close to 600 tests. However, there is still work to be done:

  • Documentation
  • TOLOG integration
  • Extensibility
  • Dedicated clients (javascript, java, …)

For this last point we ask you for help. If you are an Ontopia enthusiast that has experience in creating REST clients and that wants to help us out, please let us know!

How to get it

Ontopia REST will be added to the next major release of Ontopia. You can build it from source if you would like to use or test it before the release. You can find the source in the ontopia-rest directory in the master branch.

 

Open source perks

With the move to GitHub, several perks of being an open source project came to light:

Travis-CI

travis-mascot-200pxGitHub has a nice integration with Travis-CI, which offers free continuous integration for open source projects. Every push to a branch or pull-request branch can lead to a build and test of the project. The configuration of the build process is contained in the repository so that each branch may determine it’s own testing parameters.

We’ve enabled the Travis-CI functionality for the main Ontopia repository, and the results are publically available:

Screen Shot 2016-07-07 at 14.45.54

The automated building and testing will assist the developers with determining if branches or pull requests can be merged into the master branch or more work should be done first.

Codacy

SyZuYA39_400x400Codacy offers code analysis and measurements in a cloud service model. These measures can uncover possible improvements of the project. Improvements such as coding style, performance and security threats.

As with Travis, use of Codacy is free for open source projects. The analysis and measurements of Ontopia are publically available.

Some of the issues Codacy reports are a good practice exercise for people that would like to contribute to the project without needed a full in-depth understanding of all the code. Feel free to open merge requests referencing the issues you resolve.

Ontopia has moved to GitHub

It might be old news to the members of the Ontopia mailinglist, but we kinda forgot to update the rest of the world. So here it is.

As Google announced to shut down GoogleCode back in March 2015, we set out to find a new home for the Ontopia code base. GoogleCode would go into read-only mode in August, so we had to find a new home before this happened or we would loose the ability to commit new changes to Ontopia. Continue reading Ontopia has moved to GitHub