docs/Makefile

   1 # Copyright (c) 2021 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13 #
  14 # We support MacOS for docs generation
  15 ifeq ($(shell uname),Darwin)
  16 OS_ID = darwin
  17 endif
  18
  19 # These should be passed in by the root Makefile
  20 WS_ROOT ?= $(CURDIR)/..
  21 BR ?= $(WS_ROOT)/build-root
  22 DOCS_DIR ?= $(WS_ROOT)/docs
  23
  24 SPHINX_SCRIPTS_DIR ?= $(WS_ROOT)/docs/scripts
  25
  26 # Work out the OS if we haven't already
  27 OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g')
  28 OS_VERSION ?= $(shell grep '^VERSION_ID=' /etc/os-release  | cut -f2- -d= | sed -e 's/\"//g')
  29 PIP_VERSION ?= $(shell grep 'PIP_VERSION=' ${WS_ROOT}/test/Makefile | cut -d'=' -f2)
  30 PIP_TOOLS_VERSION ?= $(shell grep 'PIP_TOOLS_VERSION=' ${WS_ROOT}/test/Makefile | cut -d'=' -f2)
  31
  32 PYTHON ?= "python3"
  33 PYTHON_VERSION_OK := $(shell $(PYTHON) -c "exec('import sys\nif sys.hexversion >= 0x03070000: print(\"true\")\nelse: print(\"false\")')")
  34 ifneq ($(PYTHON_VERSION_OK),true)
  35 $(error "ERROR: docs build requires python version >= to 3.7")
  36 endif
  37
  38 # You can set these variables from the command line.
  39 SPHINXOPTS        = --keep-going -n -W
  40 SPHINXBUILD       = sphinx-build
  41 SPHINXPROJ        = fdio-vpp
  42 BUILDDIR          = ${BR}/docs
  43 BUILDDIR_SRC      = ${BUILDDIR}/src
  44 BUILDDIR_OUT      = ${BUILDDIR}/html
  45 SCRIPTS_DIR       = _scripts
  46 VENV_DIR          ?= $(BUILDDIR)/venv
  47
  48
  49 # Put it first so that "make" without argument is like "make help".
  50 .PHONY: help
  51 help:
  52         @( \
  53           . ${VENV_DIR}/bin/activate; \
  54           $(SPHINXBUILD) --help ;\
  55         )
  56
  57 .PHONY: venv
  58 venv:
  59         @( \
  60             if [ ! -d ${VENV_DIR} ]; then \
  61               ${PYTHON} -m venv ${VENV_DIR}; \
  62               . ${VENV_DIR}/bin/activate; \
  63               ${PYTHON} -m pip install pip==${PIP_VERSION}; \
  64               ${PYTHON} -m pip install pip-tools==${PIP_TOOLS_VERSION}; \
  65               ${PYTHON} -m pip install -r ${WS_ROOT}/test/requirements-3.txt; \
  66             fi; \
  67         )
  68
  69 .PHONY: spell
  70 spell: venv
  71         @( \
  72           . ${VENV_DIR}/bin/activate; \
  73           make -C ${SCRIPTS_DIR} generate && \
  74           $(SPHINXBUILD) -b spelling $(SPHINXOPTS) $(BUILDDIR_SRC) $(BUILDDIR_OUT); \
  75         )
  76
  77 .PHONY: rebuild-spell
  78 rebuild-spell: clean spell
  79
  80 .PHONY: docs
  81 docs: venv
  82         @( \
  83           . ${VENV_DIR}/bin/activate; \
  84           make -C ${SCRIPTS_DIR} generate && \
  85           $(SPHINXBUILD) $(SPHINXOPTS) -b html $(BUILDDIR_SRC) $(BUILDDIR_OUT); \
  86         )
  87
  88 .PHONY: rebuild
  89 rebuild: clean docs
  90
  91 .PHONY: clean
  92 clean:
  93         @make -C ${SCRIPTS_DIR} clean
  94
  95 .PHONY: build
  96 build: docs