From 6de32378f67f9a1368000a94defa8956c3c7319d Mon Sep 17 00:00:00 2001 From: Madhukar Pappireddy Date: Tue, 28 Jan 2020 12:41:20 -0600 Subject: [PATCH] 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 --- Makefile | 10 +++++++++- docs/change-log-upcoming.rst | 2 +- docs/getting_started/docs-build.rst | 21 ++++++++++++++------- 3 files changed, 24 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index bd52c0bd7..b8de647d3 100644 --- a/Makefile +++ b/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 "" diff --git a/docs/change-log-upcoming.rst b/docs/change-log-upcoming.rst index 3d7d5094d..14280cbf7 100644 --- a/docs/change-log-upcoming.rst +++ b/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" diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst index c5625e98d..91b1b3a39 100644 --- a/docs/getting_started/docs-build.rst +++ b/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 -important to note that you will not get the correct result if the commands are -run from the project root directory, as that would invoke the top-level Makefile -for |TF-A| itself. +Documents can be built into HTML-formatted pages from project root directory by +running the following command. .. code:: shell - make clean - make html + make doc Output from the build process will be placed in: :: - /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 --------------