Introduction:
Liferay Portal Framework is an open source software which is fully
customizable and easy to configure which can be used to create and manage
internet or intranet applications. For any open source software documentation
is very 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 PDF.
Recently, I came to know that Liferay also provides an automated
system to generate documentation in various formats. So I thought of giving it
a shot and once I was successful in generating the documentation I wanted to
share the information 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:
- Liferay Documentation Source Code
- Apache Ant 1.6 or higher
- Pandoc (Download from this link based on the OS Type)
Installation:
- Liferay Documentation Source Code Setup
In order to get the
source code there are two alternatives 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.
- 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:
- 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 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=Author Name date=CALENDAR_DATE
- In the properties file there is a property called “pandoc.app” is the most important property to be modified. As per my experience getting installation Path of Pandoc on Windows is bit tricky as you will not find the installed pandoc folder in “Program Files”. So I will recommend you to check out this location C:/Users/COMPUTER_NAME/AppData/Local/Pandoc
Generating Documents:
- Currently Liferay provides conversion from Markdown to HTML and ODT format and following are the commands
Aggregate the chapters into a single Markdown
file and convert to HTML,
ant markdown-to-html
Aggregate the chapters into a single Markdown
file and convert to ODT,
ant markdown-to-odt
Convert a single Markdown chapter file (e.g.
01-intro.markdown) to HTML,
ant chapter-to-html -Dchapter=01-intro
- Once you execute any of the commands mentioned above we can generate Liferay documentation very easily.
Advantages:
- If using GitHub to fetch the source code then we can have latest documentation as soon as there is an update on Liferay GitHub.
- If planning to create wiki of Liferay for internal usage through an intranet application then these chapter wise HTML contents becomes very handy.
No comments:
Post a Comment