Add support for documentation build as a target in Makefile

Command to build HTML-formatted pages from docs:
make doc

Change-Id: I4103c804b3564fe67d8fc5a3373679daabf3f2e9
Signed-off-by: Madhukar Pappireddy <madhukar.pappireddy@arm.com>

Makefile

@@ -695,6 +695,9 @@ PYTHON			?=	python3
 PRINT_MEMORY_MAP_PATH		?=	tools/memory
 PRINT_MEMORY_MAP		?=	${PRINT_MEMORY_MAP_PATH}/print_memory_map.py
 
+# Variables for use with documentation build using Sphinx tool
+DOCS_PATH		?=	docs
+
 ################################################################################
 # Include BL specific makefiles
 ################################################################################
@@ -869,7 +872,7 @@ endif
 # Build targets
 ################################################################################
 
-.PHONY:	all msg_start clean realclean distclean cscope locate-checkpatch checkcodebase checkpatch fiptool sptool fip fwu_fip certtool dtbs memmap
+.PHONY:	all msg_start clean realclean distclean cscope locate-checkpatch checkcodebase checkpatch fiptool sptool fip fwu_fip certtool dtbs memmap doc
 .SUFFIXES:
 
 all: msg_start
@@ -1067,6 +1070,10 @@ romlib.bin: libraries
 memmap: all
 	${Q}${PYTHON} $(PRINT_MEMORY_MAP) $(BUILD_PLAT)
 
+doc:
+	@echo "  BUILD DOCUMENTATION"
+	${Q}${MAKE} --no-print-directory -C ${DOCS_PATH} html
+
 cscope:
 	@echo "  CSCOPE"
 	${Q}find ${CURDIR} -name "*.[chsS]" > cscope.files
@@ -1107,6 +1114,7 @@ help:
 	@echo "  sptool         Build the Secure Partition Package creation tool"
 	@echo "  dtbs           Build the Device Tree Blobs (if required for the platform)"
 	@echo "  memmap         Print the memory map of the built binaries"
+	@echo "  doc            Build html based documentation using Sphinx tool"
 	@echo ""
 	@echo "Note: most build targets require PLAT to be set to a specific platform."
 	@echo ""

docs/change-log-upcoming.rst

@@ -23,7 +23,7 @@ New Features
    - Example: "Add support for Branch Target Identification (BTI)"
 
 - Build System
-   - Example: "Add support for default stack-protector flag"
+   - Add support for documentation build as a target in Makefile
 
 - CPU Support
    - Example: "cortex-a55: Workaround for erratum 1221012"

docs/getting_started/docs-build.rst

@@ -56,21 +56,28 @@ as root or using ``sudo``.
 Building rendered documentation
 -------------------------------
 
-From the ``docs`` directory of the project, run the following commands. It is
+Documents can be built into HTML-formatted pages from project root directory by
-important to note that you will not get the correct result if the commands are
+running the following command.
-run from the project root directory, as that would invoke the top-level Makefile
-for |TF-A| itself.
 
 .. code:: shell
 
-   make clean
+   make doc
-   make html
 
 Output from the build process will be placed in:
 
 ::
 
-   <tf-a root>/docs/build/html/
+   docs/build/html/
+
+We also support building documentation in other formats. From the ``docs``
+directory of the project, run the following command to see the supported
+formats. It is important to note that you will not get the correct result if
+the command is run from the project root directory, as that would invoke the
+top-level Makefile for |TF-A| itself.
+
+.. code:: shell
+
+   make help
 
 --------------