doc: Formatting fixes for readme.rst

The readme.rst file in the project root is the front-page that
is displayed on Github and if viewing the TF-A repository on
git.trustedfirmware.org in the "about" view. It now contains a
small amount of stub content, and directs readers to the
ReadTheDocs documentation via trustedfirmware.org/docs/tf-a.

The Github renderer is displaying the content fine but the cgit
viewer displays some "backlink" errors because some content
substitutions were left in place (terms surrounded by pipe
symbols), e.g. |TF-A|.

This patch removes those substitutions, that are not supported
by cgit, and also updates one heading to clarify where to find
the new docs.

Change-Id: I358451df45b8c99975ba0b6db8ea61253a10560d
Signed-off-by: Paul Beesley <paul.beesley@arm.com>