Writing documentation or user guide isn’t the most interesting part of the software project but it’s still needed to be done and important for the end users. There are many ways to achieve documentation but using Markdown is good way to make it easier. After that you just need to convert it to HTML and as I couldn’t find a suitable Maven plugin to do that nicely I wrote one myself: markdown-page-generator-plugin.
Software developers are a bit lazy to write good and up to date documentation and as I needed to write the API documentation for the web application as separate HTML pages I got to know the issue first hand. I like writing documents but typing the API documentation as static HTML wasn’t very effective or fun. Fortunately it was quite easy to do it with Markdown which allows you to write documentation using an easy-to-read, easy-to-write plain text format which you can then convert to HTML. After that the only problem was to enable easy HTML generation directly from Maven Lifecycle and thus was the “Markdown to HTML Page Generator Maven Plugin” developed.
Markdown to HTML Page Generator Maven Plugin
“Markdown to HTML Page Generator” is a simple Maven Plugin which reads the input directory for Markdown files with .md suffix and outputs HTML files to target directory. There are couple of configuration options to set the input/output directories and if you want to add header and footer files to make it structurally valid HTML. The plugin uses pegdown Markdown processor.
The plugin code can be found from GitHub: markdown-page-generator-plugin.
Check out the plugin’s GitHub page for configuration options.
Using the plugin could be easier but as it isn’t in Maven repository you have to e.g. add it as Maven project to same Eclipse workspace as your project and build it. After that add it as a plugin to your build and it’s run automatically when processing sources. You can also run it from command line with “mvn com.ruleoftech:markdown-page-generator-plugin:generate”.
Setting up LAMP stack for web development on OS X can be done with 3rd party software like MAMP but as Mac OS X comes with pre-installed Apache and PHP it’s easy to use the native setup. You just need to configure Apache, PHP and install MySQL.
Set up the Server Name to localhost to suppress the warning about fully qualified domain name and enable PHP module.
$ sudo vim /etc/apache2/httpd.conf
LoadModule php5_module libexec/apache2/libphp5.so
Create “virtual hosts” under your Sites. Change the username to your account’s username.
~$ sudo vim /etc/apache2/users/username.conf
Allow from all
Now Apache serves your projects from your home directory’s Sites folder. Apache will serve files from the htdocs folder like “~/Sites/projectname/htdocs”.
Now just restart Apache and check that it’s running.
$ sudo apachectl restart
$ ps aux | grep httpd
$ sudo cp /etc/php.ini.default /etc/php.ini
Edit php.ini for easier debugging:
error_reporting = E_ALL | E_STRICT
display_errors = On
html_errors = On
MySQL can be installed directly from Oracle’s MySQL packages or by using Homebrew.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install MySQL using Homebrew
Install the MySQL system tables and have it run as your system user:
$ unset TMPDIR
$ mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/usr/local/var/mysql --tmpdir=/tmp
Start MySQL and check that it’s running
$ mysql.server start
$ ps aux | grep mysql
Reset the root password. Change the “5.5.27” to your installed version number.
$ /usr/local/Cellar/mysql/5.5.27/bin/mysqladmin -u root password 'YOUR_NEW_PASSWORD'
As we are using the Homebrew package for MySQL and the default php.ini file then PHP is trying to connect to MySQL through the default_socket at /var/mysql/mysql.sock which doesn’t exist as MySQL is using /tmp/mysql.sock. Just change all instances of /var/mysql/mysql.sock to /tmp/mysql.sock.
$ sudo sed -i "" "s:/var/mysql/mysql.sock:/tmp/mysql.sock:g" /etc/php.ini
And you’re done.