doc: Update user guide and version numbers

This commit updates the user guide and supporting documentation to bring
it in-line with the latest v2.5.0 release. It changes the Markdown
header syntax in order to represent deeper header levels, replaces old
links and attempts to clear up areas of potential confusion with
instructions.

Change-Id: I99b464a4bc94f4618779fbe09b1aa77bed0c318e
Signed-off-by: Chris Kay <chris.kay@arm.com>