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