doc/Makefile

   1 # Build and safety-check requirements.txt
   2
   3 # skjold needs a personal github access token.  This needs no permissions,
   4 # it is only required to query the GitHub GraphQL API v4.
   5 # See: https://pythonawesome.com/security-audit-python-project-dependencies-against-security-advisory-databases/
   6 # We attempt to get it from the environment variable SKJOLD_GITHUB_API_TOKEN
   7 # or GITHUB_TOKEN.
   8 # It can also be passed to this Makefile via either:
   9 #
  10 #   make GITHUB_TOKEN=... (build-and-)check-requirements
  11 #   make SKJOLD_GITHUB_API_TOKEN=... (build-and-)check-requirements
  12 #
  13 #
  14 SKJOLD_GITHUB_API_TOKEN ?= ${GITHUB_TOKEN}
  15 # TODO: when we have sphinx-build2 ?
  16 SPHINXCMD:=sphinx-build
  17 # Flag -n ("nitpick") warns about broken references
  18 # Flag -W turns warnings into errors
  19 # Flag --keep-going continues after errors
  20 SPHINX_FLAGS:=-n -W --keep-going -E
  21 SPHINX_HTML_OUTDIR:=../dist-newstyle/doc/users-guide
  22 USERGUIDE_STAMP:=$(SPHINX_HTML_OUTDIR)/index.html
  23 PYTHON_VIRTUALENV_ACTIVATE:=../.python-sphinx-virtualenv/bin/activate
  24
  25 # Python virtual environment
  26 ##############################################################################
  27
  28 # Create a python virtual environment in the root of the cabal repository.
  29 $(PYTHON_VIRTUALENV_ACTIVATE):
  30         python3 -m venv ../.python-sphinx-virtualenv
  31         (. $(PYTHON_VIRTUALENV_ACTIVATE))
  32
  33 # Users guide
  34 ##############################################################################
  35
  36 # do pip install every time so we have up to date requirements when we build
  37 users-guide: $(PYTHON_VIRTUALENV_ACTIVATE) $(USERGUIDE_STAMP)
  38 $(USERGUIDE_STAMP) : *.rst
  39         mkdir -p $(SPHINX_HTML_OUTDIR)
  40         (. $(PYTHON_VIRTUALENV_ACTIVATE) && pip install -r requirements.txt && $(SPHINXCMD) $(SPHINX_FLAGS) . $(SPHINX_HTML_OUTDIR))
  41
  42 # Requirements
  43 ##############################################################################
  44
  45 ##
  46 # This goal is intended for manual invocation, always rebuilds.
  47 .PHONY: users-guide-requirements
  48 users-guide-requirements: requirements.txt
  49
  50 .PHONY: build-and-check-requirements
  51 build-and-check-requirements: requirements.txt check-requirements
  52
  53 # Always rebuild requirements.txt
  54 .PHONY: requirements.txt
  55 # requirements.txt is generated from requirements.in
  56 # via pip-compile included in the pip-tools package.
  57 # See https://modelpredict.com/wht-requirements-txt-is-not-enough
  58 requirements.txt: requirements.in $(PYTHON_VIRTUALENV_ACTIVATE)
  59         . $(PYTHON_VIRTUALENV_ACTIVATE) \
  60           && pip install --upgrade pip \
  61           && pip install pip-tools \
  62           && pip-compile requirements.in
  63
  64 # Check requirements.txt for security violations via skjold,
  65 # configured in pyproject.toml.
  66 # See: https://pythonawesome.com/security-audit-python-project-dependencies-against-security-advisory-databases/
  67 .PHONY: check-requirements
  68 check-requirements:
  69         @if [ -z "$${SKJOLD_GITHUB_API_TOKEN}" ] \
  70         ; then \
  71           echo "WARNING: Neither SKJOLD_GITHUB_API_TOKEN nor GITHUB_TOKEN is set." \
  72         ; echo "Vulnerability check via skjold might fail when using the GitHub GraphQL API." \
  73         ; fi
  74         . $(PYTHON_VIRTUALENV_ACTIVATE) \
  75           && pip install skjold \
  76           && skjold audit
  77 # NB: For portability, we use '.' (sh etc.) instead of 'source' (bash).
  78
  79 # Debug print environment variables
  80 debug:
  81         @echo "GITHUB_TOKEN = ${GITHUB_TOKEN}"
  82         @echo "SKJOLD_GITHUB_API_TOKEN = $${SKJOLD_GITHUB_API_TOKEN}"
  83         @echo "Is SKJOLD_GITHUB_API_TOKEN set? $${SKJOLD_GITHUB_API_TOKEN:+yes}"
  84
  85 # EOF