1OS := $(shell uname -s) 2SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"): 3PLUGIN_FORMATTER=../../hacking/build-ansible.py docs-build 4TESTING_FORMATTER=../bin/testing_formatter.sh 5KEYWORD_DUMPER=../../hacking/build-ansible.py document-keywords 6CONFIG_DUMPER=../../hacking/build-ansible.py document-config 7GENERATE_CLI=../../hacking/build-ansible.py generate-man 8COLLECTION_DUMPER=../../hacking/build-ansible.py collection-meta 9ifeq ($(shell echo $(OS) | egrep -ic 'Darwin|FreeBSD|OpenBSD|DragonFly'),1) 10CPUS ?= $(shell sysctl hw.ncpu|awk '{print $$2}') 11else 12CPUS ?= $(shell nproc) 13endif 14 15# Intenationalisation and Localisation 16LANGUAGES ?= 17 18# Sets the build output directory for the main docsite if it's not already specified 19ifndef BUILDDIR 20 BUILDDIR = _build 21endif 22 23ifndef POTDIR 24 POTDIR = $(BUILDDIR)/gettext 25endif 26 27# Backwards compat for separate VARS 28PLUGIN_ARGS= 29ifdef MODULES 30ifndef PLUGINS 31 PLUGIN_ARGS = -l $(MODULES) 32else 33 PLUGIN_ARGS = -l $(MODULES),$(PLUGINS) 34endif 35else 36ifdef PLUGINS 37 PLUGIN_ARGS = -l $(PLUGINS) 38endif 39endif 40 41ANSIBLE_VERSION_ARGS= 42ifdef ANSIBLE_VERSION 43 ANSIBLE_VERSION_ARGS=--ansible-version=$(ANSIBLE_VERSION) 44endif 45 46DOC_PLUGINS ?= become cache callback cliconf connection httpapi inventory lookup netconf shell strategy vars 47 48PYTHON=python 49# fetch version from project release.py as single source-of-truth 50VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --raw || echo error) 51ifeq ($(findstring error,$(VERSION)), error) 52$(error "version_helper failed") 53endif 54 55MAJOR_VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --majorversion || echo error) 56ifeq ($(findstring error,$(MAJOR_VERSION)), error) 57$(error "version_helper failed to determine major version") 58endif 59 60assertrst: 61ifndef rst 62 $(error specify document or pattern with rst=somefile.rst) 63endif 64 65all: docs 66 67docs: htmldocs 68 69coredocs: core_htmldocs 70 71generate_rst: collections_meta config cli keywords plugins testing 72core_generate_rst: collections_meta config cli keywords base_plugins testing 73 74# At the moment localizing the plugins and collections is not required for the ongoing 75# localisation effort. It will come at a later time. 76gettext_generate_rst: collections_meta config cli keywords testing 77 78# The following two symlinks are necessary to produce two different docsets 79# from the same set of rst files (Ansible the package docs, and core docs). 80# Symlink the relevant index into place for building Ansible docs 81ansible_structure: generate_rst 82 # We must have python and python-packaging for the version_helper 83 # script so use it for version comparison 84 if python -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \ 85 echo "Creating symlinks in generate_rst"; \ 86 ln -sf ../rst/ansible_index.rst rst/index.rst; \ 87 ln -sf ../sphinx_conf/ansible_conf.py rst/conf.py; \ 88 else \ 89 echo 'Creating symlinks for older ansible in generate_rst'; \ 90 ln -sf ../rst/2.10_index.rst rst/index.rst; \ 91 ln -sf ../sphinx_conf/2.10_conf.py rst/conf.py; \ 92 fi 93 94# Symlink the relevant index into place for building core docs 95core_structure: core_generate_rst 96 @echo "Creating symlinks in core_generate_rst" 97 -ln -sf ../rst/core_index.rst rst/index.rst 98 -ln -sf ../sphinx_conf/core_conf.py rst/conf.py 99 100# Symlink the relevant index into place for building core docs 101gettext_structure: gettext_generate_rst 102 @echo "Creating symlinks in gettext_generate_rst" 103 -ln -sf ../rst/core_index.rst rst/index.rst 104 -ln -sf ../sphinx_conf/all_conf.py rst/conf.py 105 106gettext: gettext_structure 107 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx gettext 108 # if msgcat is installed handle all indexes, otherwise use the index from gettext_structure. 109 -msgcat "$(POTDIR)/core_index.pot" "$(POTDIR)/ansible_index.pot" "$(POTDIR)/2.10_index.pot" > "$(POTDIR)/tmp_index.pot" && mv "$(POTDIR)/tmp_index.pot" "$(POTDIR)/index.pot" 110 rm "$(POTDIR)/core_index.pot" "$(POTDIR)/ansible_index.pot" "$(POTDIR)/2.10_index.pot" 111 112generate-po: 113ifeq ($(LANGUAGES),) 114 @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' 115else 116 (cd docs/docsite/; sphinx-intl update -w 0 -d rst/locales -p "$(POTDIR)" -l $(LANGUAGES)) 117endif 118 119needs-translation: 120ifeq ($(LANGUAGES),) 121 @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' 122else 123 (cd docs/docsite/; sphinx-intl stat -d rst/locales -l $(LANGUAGES) | grep -E ' [1-9][0-9]* (fuzzy|untranslated)' | sort) 124endif 125 126htmldocs: ansible_structure 127 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html 128 129core_htmldocs: core_structure 130 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html 131 132singlehtmldocs: ansible_structure 133 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml 134 135core_singlehtmldocs: core_structure 136 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml 137 138linkcheckdocs: generate_rst 139 CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck 140 141webdocs: docs 142 143#TODO: leaving htmlout removal for those having older versions, should eventually be removed also 144clean: 145 @echo "Cleaning $(BUILDDIR)" 146 -rm -rf $(BUILDDIR)/doctrees 147 -rm -rf $(BUILDDIR)/html 148 -rm -rf htmlout 149 -rm -rf module_docs 150 -rm -rf $(BUILDDIR) 151 -rm -f .buildinfo 152 -rm -f objects.inv 153 -rm -rf *.doctrees 154 @echo "Cleaning up minified css files" 155 find . -type f -name "*.min.css" -delete 156 @echo "Cleaning up byte compiled python stuff" 157 find . -regex ".*\.py[co]$$" -delete 158 @echo "Cleaning up editor backup files" 159 find . -type f \( -name "*~" -or -name "#*" \) -delete 160 find . -type f \( -name "*.swp" \) -delete 161 @echo "Cleaning up generated rst" 162 rm -f rst/playbooks_directives.rst 163 rm -f rst/reference_appendices/config.rst 164 rm -f rst/reference_appendices/playbooks_keywords.rst 165 rm -f rst/dev_guide/collections_galaxy_meta.rst 166 rm -f rst/cli/*.rst 167 for filename in `ls rst/collections/` ; do \ 168 if test x"$$filename" != x'all_plugins.rst' ; then \ 169 rm -rf "rst/collections/$$filename"; \ 170 fi \ 171 done 172 @echo "Cleanning up generated ansible_structure" 173 find -type l -delete 174 @echo "Cleaning up legacy generated rst locations" 175 rm -rf rst/modules 176 rm -f rst/plugins/*/*.rst 177 178.PHONY: docs clean 179 180collections_meta: ../templates/collections_galaxy_meta.rst.j2 181 $(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml 182 183# TODO: make generate_man output dir cli option 184cli: 185 mkdir -p rst/cli 186 $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py 187 188keywords: ../templates/playbooks_keywords.rst.j2 189 $(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ../../lib/ansible/keyword_desc.yml 190 191config: ../templates/config.rst.j2 192 $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml 193 194# For now, if we're building on devel, just build base docs. In the future we'll want to build docs that 195# are the latest versions on galaxy (using a different antsibull-docs subcommand) 196plugins: 197 $(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(PLUGIN_ARGS);\ 198 199# This only builds the plugin docs included with ansible-core 200base_plugins: 201 $(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\ 202 203testing: 204 $(TESTING_FORMATTER) 205 206epub: 207 (CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub) 208 209htmlsingle: assertrst 210 sphinx-build -j $(CPUS) -b html -d $(BUILDDIR)/doctrees ./rst $(BUILDDIR)/html rst/$(rst) 211 @echo "Output is in $(BUILDDIR)/html/$(rst:.rst=.html)" 212