Back

Generating Liferay 6.1/6.2 Documentation

Posted 10/23/13
0 Comment

Introduction:

Liferay Portal Framework is an open source software- which is fully customizable and easy to configure- can be used to create and manage internet or intranet applications. With any open source software, documentation is critical as it helps its users to understand the software much better. Liferay have been providing documentation for all the previous Liferay versions in the form of PDFs.

Recently, I learned that Liferay also provides an automated system to generate documentation in various formats. So I gave it a shot and once I was successful in generating the documentation I wanted to share it so that anybody who seeks to have their own copy of documentation of Liferay can generate it very easily.

Currently Liferay provides this automated document generation mechanism for Liferay versions 6.1(CE & EE) and 6.2 (CE & EE).

 

Pre-requisites:

  1. Liferay Documentation Source Code
  2. Apache Ant 1.6 or higher
  3. Pandoc (Download from this link based on the OS Type)

 

Installation:

        1. Liferay Documentation Source Code Setup

To get the source code there are two options. Either you can use GIT to clone the source code in your local system, or you can download directly the source code zip file from this link. Click on the Download Zip button as shown below:

 

For Liferay version 6.1.x Documentation use this link and for 6.2.x use this link. If you want to download version specific then you can use this link too.

2. Pandoc Installation

Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. It can read markdown and (subsets of) reStructuredText, HTML, Textile, DocBook, and LaTeX, and it can write markdown, reStructuredText, Textile, HTML, LaTeX, ConTeXt, Docbook XML, OpenDocument XML, GNU Texinfo, Emacs Org-mode, RTF, ODT, MediaWiki markup, groff man pages, EPUB, and S5 and Slidy HTML slide shows.

Pandoc extends standard markdown syntax with footnotes, embedded LaTeX, definition lists, tables, and many other features. A compatibility mode is provided for those who need a drop-in replacement for Markdown.pl.

Follow the Installation instructions provided at this link.

 

Configuration:

  1. Source Code Configuration
  • After downloading the source code(assuming Liferay version 6.1.x) you will have a zip file named as 6.1.x.zip.
  • Unzip the file and rename the folder to “liferay-docs”.
  • Contents of the folder will be as shown below:
  • We need to override the properties in the build.properties, so create a file and provide name as build.COMPUTER_NAME.properties as shown below.
  • After creating the file we need to override following properties:

# Overridden Properties

  pandoc.app=PANDOC_INSTALLATION_PATH

  title=Liferay Documentation

  author=Dunn Solutions Group       

  date=CALENDAR_DATE

  • In the properties file there is a property called “pandoc.app”- it is the most important property to be modified in my experience of installations.  Path of Pandoc on Windows is bit tricky as you will not find the installed pandoc folder in “Program Files”. So I recommend that you to check out this location: C:/Users/COMPUTER_NAME/AppData/Local/Pandoc

 

Generating Documents:

  1. Currently Liferay provides conversion from Markdown to HTML and ODT format and following are the commands
  1. Aggregate the chapters into a single Markdown file and convert to HTML,

ant markdown-to-html

  1. Aggregate the chapters into a single Markdown file and convert to ODT,

ant markdown-to-odt

  1. convert a single Markdown chapter file (e.g. 01-intro.markdown) to HTML,

ant chapter-to-html -Dchapter=01-intro

  1. Once you execute any of the commands mentioned above we can generate Liferay documentation very easily.

 

Advantages:

  1. If using GitHub to fetch the source code then we can have latest documentation as soon as there is an update on Liferay GitHub.
  2. If planning to create wiki of Liferay for internal usage through an intranet application then these chapter wise HTML contents becomes very handy.

 

Comments
No comments yet. Add Comment

Contact Us

character(s) remaining