Got documentation as markdown and PlantUMl in maven project?

Somehow I have not written a note about this before.

Maven site plugin can help you to publish your documentation — also if it is written in markdown. You just need to use doxia-module-markdown module and configure it to be used with the site.

See instructions and tips from here: http://stackoverflow.com/questions/14829190/how-to-use-markdown-for-maven-project-site

You can add also PlantUML plugin into pom and transform your PlantUML drawings into PNG and written into site’s output directory.

However if you want to get the site built during the normal phases instead running mvn site — and for example package the site into a web application, you need to command both PlantUML and site plugins to run during the compile phase. Executions tag is just the perfect way to do that.

 

PlantUML plugin can be run with the following configuration added to plugin configuration.

<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<phase>compile</phase>
</execution>
</executions>

 

And site plugin can be run with following:

<executions>
<execution>
<goals>
<goal>site</goal>
</goals>
<phase>compile</phase>
</execution>
</executions>

Configuration can be added to direct output to a specific places:

<configuration>
<outputDirectory>${project.basedir}/target/war-docs-1.0/</outputDirectory>
</configuration>

In the above case we are directing the output to a web application’s directory to be packaged into the application. This way we are able to build and package a web application in singe stroke — and include also related documentation with it.

How cool is that.

Kategoria(t): programming, technology | Jätä kommentti

SublimeText + Markdown Preview + Live Reload = epic markdown writing environment

I’ve been a fan of Sublime Text for some time, but not taken many of it’s features into full use. One of those features I neglected for some time was usage of plugins, which turbocharge already awesome editor.

As I am very fond of Markdown and it’s use as a convenient documentation writing language, the first plugins I wanted to try and use were plugins to preview markdown text while I am writing it. Though the markdown plugin inside IntelliJ idea is great and I like to use it a lot, there are numerous situations where I just want to quickly write and edit some documentation outside the IDE — hence my interest to get this work!

Markdown Preview was installed easily just following the instructions to install the Package Control and then straight from the repository. After installation Markdown Preview commands were available as commands.

By using cmd+shift+P and selecting ’Markdown Preview: Python Markdown: Preview in Browser’ plugin would render my markdown into temporary file and open it in browser.

See download and instructions from here: https://github.com/revolunet/sublimetext-markdown-preview

Functionality is almost perfect straight out of the box.

Only gripe is the need to manually refresh the browser after saves. I know. Truly a first world problem.

Luckily a little help comes from another plugin, LiveReload.

See more here: https://github.com/dz0ny/LiveReload-sublimetext2/tree/devel

I had problem getting the LiveReload plugin first to work properly – as I did not understand that you had to manually enable the LiveReload plugin for specific behaviour. Only after I selected from command palette command to Enable LiveReload plugins and enabled Simple reload things started to work as requested.

See the video above how live reload works and updates the browser every time the document gets saved.

Me likes!

Kategoria(t): technology | Jätä kommentti

Some new posts in finnish blog: Lumia 1020, 3h delivery service from Verkkokauppa.com and admiration for 4k displays

First one:

How Lumia 1020 feels after iPhone

… Verdict. Feels like the best camera with integrated phone.

Verkkokauppa.com offers new fast deliveries from their warehouse to anywhere in Helsinki in 3 hours for 9,90 ( regular pricing will be / can be different in the future ). Future is here.

I did not understand what the fuss with 4K was, until I saw one in real life. Yes please, when the prices come to more rational level for consumers.

4k display for programmers will be HUGE productivity booster.

Kategoria(t): business, life | Jätä kommentti

PlantUML and Markdown for quick documentation

Writing documentation is so much fun.

Though we all always aim to write code that clearly communicates the ideas and intentions of our code, there are still moments where we need to write documentation and describe something to our colleagues. And when we need to do that, what programs should we use so that also our colleagues could update the documentation and the living nature of documentation would be fulfilled?

What has worked in some projects for me, has been the combination of PlantUML and Markdown — with a dash of integration into IDE and maven plugin or a hint of Python script to do transformations into HTML.

PlantUML is extremely unsexy project to provide capability to define UML graphs in text and create pictures from them automatically.

A cool sequence graph like this:

Could be created with a text like below:


@startuml
actor serviceperson
boundary Siebel
participant Cognos
participant MessageBroker
participant "Alfresco Api"
participant Portal
actor Customer

title Sequence diagram describing how different actors interact in Service Report-integration
serviceperson -> Siebel : register report
Cognos -> Siebel : analyse data
Cognos -> Cognos : launch report generation, \n generate files to disk
MessageBroker -> Cognos : Read metadata and files
MessageBroker -> MessageBroker: Transform message
MessageBroker -> "Alfresco Api" : post the file and metadata
"Alfresco Api" -> MessageBroker : respond OK or error \n create new file or \n replace existing file

Portal -> "Alfresco Api" : Search reports
"Alfresco Api" -> Portal : Response listing\n with download links
Portal -> Customer : Present listings
Customer -> Portal : Request download
Portal -> "Alfresco Api": Download file
Portal -> Customer: Stream file to user
@enduml

Fast to write. Fast to understand.

Drive the point home better than with a longer prose or ASCII graphs.

Then what about Markdown? How does that fit into the picture?

Markdown syntax allows you to create really quick formatting to your text and transform that to HTML later on. Once again makes you a bit more agile in writing your thoughts down and describing them to your colleagues.

And the good part?

Most likely your IDE or editor already has some kind of support for these syntaxes, making your work and workflow even more smoother — allowing you to preview your graphs and documents fast.

PlanUml plugin

Markdown plugin

Above examples show plugins in IntelliJ Idea.

Otherwise depending on your workflow you could integrate graph generation and markdown transformation into a maven phase — or do like I do, use Python script to manually generate html versions when needed.

#!/usr/bin/env python
#
# This script transforms markdown and plantuml documents into html-files and png-images
#
# Transformed images are put into html subdirectory
#

import os, sys
from fnmatch import fnmatch

def ensure_dir(f):
d = os.path.dirname(f)
if not os.path.exists(d):
os.makedirs(d)

if len(sys.argv) != 3:
print "Usage:", sys.argv[0], "" , " plantuml.jar path>"
sys.exit()

directory = sys.argv[1]
plantuml = sys.argv[2]

for path, directory, files in os.walk(directory):
for file in files:
if fnmatch(file, "*.md"):
markdown_file = "%s/%s" % (path, file)
html_dir = "%s/%s" % (path, 'html/')
ensure_dir(html_dir)
html_file = "%s%s" % (html_dir, file.replace(".md", ".html"))
os.system("markdown2 %s > %s" % (markdown_file, html_file))

if fnmatch(file, "*.puml"):
puml_file = "%s/%s" % (path, file)
print puml_file
os.system("java -jar %s %s -o html" % (plantuml, puml_file))

Above Python script traverses directory tree you give it to find Markdown files ( *.md ) and PlantUml files ( *.puml ) and creates html subdirectories into directories to store html versions of the text and png versions of graphs.

As a second parameter script requires path to plantuml.jar.

Script should be easy to understand and modify to your own needs.

With Markdown and PlantUml integrated into your coding workflow there should not be any more reasons not to write necessary documentation for your colleagues. And as everything is text based and tightly integrated into the build system & environment – anyone can update, fix and improve that documentation at the same time as they update or refactor the code.

Kategoria(t): programming, Uncategorized | Jätä kommentti

Replacement battery for old 13″ Macbook

Just ordered an OEM replacement battery for my old macbook from Ebay.de for 38 euros. I had noticed that the Macbook had started to behave strangely, complain that it does not have any load in battery and run the fan almost all the time — that did not worry me as much as the bulging in the battery I noticed today.

New battery from Apple would have cost few times more — and would have started to make more sense to actually replace the Macbook with a Raspberry Pi based HTPC. Actually I could have done that already now – but as I don’t have time to do additional hacking projects, I rather just replace the battery for now and continue using the Macbook as a living room music player.

Kategoria(t): Uncategorized | Jätä kommentti

Scan Agile 2013 videos getting uploaded online

I already blogged in Finnish on my other blog that we finally have started to upload Scan Agile 2013 videos online.

https://vimeo.com/channels/658330

Vimeo’s upload limits will limit how fast and how much we can upload, so it will be few weeks before all the videos are online.

Kategoria(t): agile, digital, life | Jätä kommentti

Windows 7 backups failed me

Ugh.

Microsoft seems to make features to all products.

I was no longer able to make system image backups from my system disk, as Windows had decided that my data disk had become a system disk and was to be included in the system image.

Even removing software that was installed to data disk and made to start in the image.

I tested and registered Macrium to handle the the job for future.

They offered 20% discount via Facebook message, so it was much more cost effective to just take it and use it — instead of trying to fix the Windows backup issue.

Kategoria(t): business, life, technology | Jätä kommentti