HRCPP-88 Document the steps required to build the api docs

https://issues.jboss.org/browse/HRCPP-88

also fixes the markup for github