ccbfdec334
* excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
174 lines
6 KiB
Makefile
174 lines
6 KiB
Makefile
OS := $(shell uname -s)
|
|
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"):
|
|
PLUGIN_FORMATTER=../../hacking/build-ansible.py docs-build
|
|
TESTING_FORMATTER=../bin/testing_formatter.sh
|
|
KEYWORD_DUMPER=../../hacking/build-ansible.py document-keywords
|
|
CONFIG_DUMPER=../../hacking/build-ansible.py document-config
|
|
GENERATE_CLI=../../hacking/build-ansible.py generate-man
|
|
COLLECTION_DUMPER=../../hacking/build-ansible.py collection-meta
|
|
ifeq ($(shell echo $(OS) | egrep -ic 'Darwin|FreeBSD|OpenBSD|DragonFly'),1)
|
|
CPUS ?= $(shell sysctl hw.ncpu|awk '{print $$2}')
|
|
else
|
|
CPUS ?= $(shell nproc)
|
|
endif
|
|
|
|
# Sets the build output directory for the main docsite if it's not already specified
|
|
ifndef BUILDDIR
|
|
BUILDDIR = _build
|
|
endif
|
|
|
|
# Backwards compat for separate VARS
|
|
PLUGIN_ARGS=
|
|
ifdef MODULES
|
|
ifndef PLUGINS
|
|
PLUGIN_ARGS = -l $(MODULES)
|
|
else
|
|
PLUGIN_ARGS = -l $(MODULES),$(PLUGINS)
|
|
endif
|
|
else
|
|
ifdef PLUGINS
|
|
PLUGIN_ARGS = -l $(PLUGINS)
|
|
endif
|
|
endif
|
|
|
|
ANSIBLE_VERSION_ARGS=
|
|
ifdef ANSIBLE_VERSION
|
|
ANSIBLE_VERSION_ARGS=--ansible-version=$(ANSIBLE_VERSION)
|
|
endif
|
|
|
|
DOC_PLUGINS ?= become cache callback cliconf connection httpapi inventory lookup netconf shell strategy vars
|
|
|
|
PYTHON=python
|
|
# fetch version from project release.py as single source-of-truth
|
|
VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --raw || echo error)
|
|
ifeq ($(findstring error,$(VERSION)), error)
|
|
$(error "version_helper failed")
|
|
endif
|
|
|
|
MAJOR_VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --majorversion || echo error)
|
|
ifeq ($(findstring error,$(MAJOR_VERSION)), error)
|
|
$(error "version_helper failed to determine major version")
|
|
endif
|
|
|
|
assertrst:
|
|
ifndef rst
|
|
$(error specify document or pattern with rst=somefile.rst)
|
|
endif
|
|
|
|
all: docs
|
|
|
|
docs: htmldocs
|
|
|
|
coredocs: core_htmldocs
|
|
|
|
generate_rst: collections_meta config cli keywords plugins testing
|
|
core_generate_rst: collections_meta config cli keywords base_plugins testing
|
|
|
|
# The following two symlinks are necessary to produce two different docsets
|
|
# from the same set of rst files (Ansible the package docs, and core docs).
|
|
# Symlink the relevant index into place for building Ansible docs
|
|
ansible_structure: generate_rst
|
|
# We must have python and python-packaging for the version_helper
|
|
# script so use it for version comparison
|
|
if python -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \
|
|
echo "Creating symlinks in generate_rst"; \
|
|
ln -sf ../rst/ansible_index.rst rst/index.rst; \
|
|
ln -sf ../sphinx_conf/ansible_conf.py rst/conf.py; \
|
|
else \
|
|
echo 'Creating symlinks for older ansible in generate_rst'; \
|
|
ln -sf ../rst/2.10_index.rst rst/index.rst; \
|
|
ln -sf ../sphinx_conf/2.10_conf.py rst/conf.py; \
|
|
fi
|
|
|
|
# Symlink the relevant index into place for building core docs
|
|
core_structure: core_generate_rst
|
|
@echo "Creating symlinks in core_generate_rst"
|
|
-ln -sf ../rst/core_index.rst rst/index.rst
|
|
-ln -sf ../sphinx_conf/core_conf.py rst/conf.py
|
|
|
|
htmldocs: ansible_structure
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
|
|
|
|
core_htmldocs: core_structure
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
|
|
|
|
singlehtmldocs: ansible_structure
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml
|
|
|
|
core_singlehtmldocs: core_structure
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml
|
|
|
|
linkcheckdocs: generate_rst
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck
|
|
|
|
webdocs: docs
|
|
|
|
#TODO: leaving htmlout removal for those having older versions, should eventually be removed also
|
|
clean:
|
|
@echo "Cleaning $(BUILDDIR)"
|
|
-rm -rf $(BUILDDIR)/doctrees
|
|
-rm -rf $(BUILDDIR)/html
|
|
-rm -rf htmlout
|
|
-rm -rf module_docs
|
|
-rm -rf $(BUILDDIR)
|
|
-rm -f .buildinfo
|
|
-rm -f objects.inv
|
|
-rm -rf *.doctrees
|
|
@echo "Cleaning up minified css files"
|
|
find . -type f -name "*.min.css" -delete
|
|
@echo "Cleaning up byte compiled python stuff"
|
|
find . -regex ".*\.py[co]$$" -delete
|
|
@echo "Cleaning up editor backup files"
|
|
find . -type f \( -name "*~" -or -name "#*" \) -delete
|
|
find . -type f \( -name "*.swp" \) -delete
|
|
@echo "Cleaning up generated rst"
|
|
rm -f rst/playbooks_directives.rst
|
|
rm -f rst/reference_appendices/config.rst
|
|
rm -f rst/reference_appendices/playbooks_keywords.rst
|
|
rm -f rst/dev_guide/collections_galaxy_meta.rst
|
|
rm -f rst/cli/*.rst
|
|
for filename in `ls rst/collections/` ; do \
|
|
if test x"$$filename" != x'all_plugins.rst' ; then \
|
|
rm -rf "rst/collections/$$filename"; \
|
|
fi \
|
|
done
|
|
@echo "Cleanning up generated ansible_structure"
|
|
find -type l -delete
|
|
@echo "Cleaning up legacy generated rst locations"
|
|
rm -rf rst/modules
|
|
rm -f rst/plugins/*/*.rst
|
|
|
|
.PHONY: docs clean
|
|
|
|
collections_meta: ../templates/collections_galaxy_meta.rst.j2
|
|
$(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml
|
|
|
|
# TODO: make generate_man output dir cli option
|
|
cli:
|
|
mkdir -p rst/cli
|
|
$(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py
|
|
|
|
keywords: ../templates/playbooks_keywords.rst.j2
|
|
$(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ../../lib/ansible/keyword_desc.yml
|
|
|
|
config: ../templates/config.rst.j2
|
|
$(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml
|
|
|
|
# For now, if we're building on devel, just build base docs. In the future we'll want to build docs that
|
|
# are the latest versions on galaxy (using a different antsibull-docs subcommand)
|
|
plugins:
|
|
$(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(PLUGIN_ARGS);\
|
|
|
|
# This only builds the plugin docs included with ansible-base
|
|
base_plugins:
|
|
$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\
|
|
|
|
testing:
|
|
$(TESTING_FORMATTER)
|
|
|
|
epub:
|
|
(CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub)
|
|
|
|
htmlsingle: assertrst
|
|
sphinx-build -j $(CPUS) -b html -d $(BUILDDIR)/doctrees ./rst $(BUILDDIR)/html rst/$(rst)
|
|
@echo "Output is in $(BUILDDIR)/html/$(rst:.rst=.html)"
|