diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
commit | 8a754e0858d922e955e71b253c139e071ecec432 (patch) | |
tree | 527d16e74bfd1840c85efd675fdecad056c54107 /docs/docsite/Makefile | |
parent | Initial commit. (diff) | |
download | ansible-core-upstream/2.14.3.tar.xz ansible-core-upstream/2.14.3.zip |
Adding upstream version 2.14.3.upstream/2.14.3upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | docs/docsite/Makefile | 220 | ||||
-rw-r--r-- | docs/docsite/Makefile.sphinx | 26 |
2 files changed, 246 insertions, 0 deletions
diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile new file mode 100644 index 0000000..f8e8759 --- /dev/null +++ b/docs/docsite/Makefile @@ -0,0 +1,220 @@ +OS := $(shell uname -s) +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 + +# Intenationalisation and Localisation +LANGUAGES ?= + +# Sets the build output directory for the main docsite if it's not already specified +ifndef BUILDDIR + BUILDDIR = _build +endif + +ifndef POTDIR + POTDIR = $(BUILDDIR)/gettext +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 core_plugins testing + +# At the moment localizing the plugins and collections is not required for the ongoing +# localisation effort. It will come at a later time. +gettext_generate_rst: collections_meta config cli keywords testing + +# The following 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: + # 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 ansible_structure"; \ + ln -sf ../rst/ansible_index.rst rst/index.rst; \ + ln -sf ../dev_guide/ansible_index.rst rst/dev_guide/index.rst; \ + ln -sf ../sphinx_conf/ansible_conf.py rst/conf.py; \ + else \ + echo 'Creating symlinks for older ansible in ansible_structure'; \ + 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: + @echo "Creating symlinks in core_structure" + -ln -sf ../rst/core_index.rst rst/index.rst + -ln -sf ../dev_guide/core_index.rst rst/dev_guide/index.rst +# set up the correct core conf.py to use for English vs a translated language +ifdef LANGOPTS + -ln -sf ../sphinx_conf/core_lang_conf.py rst/conf.py +else + -ln -sf ../sphinx_conf/core_conf.py rst/conf.py +endif + +# Symlink the relevant index into place for building core translated docs +gettext_structure: + @echo "Creating symlinks in gettext_structure" + -ln -sf ../rst/core_index.rst rst/index.rst + -ln -sf ../rst/dev_guide/core_index.rst rst/dev_guide/index.rst + -ln -sf ../sphinx_conf/all_conf.py rst/conf.py + +gettext: gettext_structure gettext_generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx gettext + # if msgcat is installed handle all indexes, otherwise use the index from gettext_structure. + -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" + rm "$(POTDIR)/core_index.pot" "$(POTDIR)/ansible_index.pot" "$(POTDIR)/2.10_index.pot" + +generate-po: +ifeq ($(LANGUAGES),) + @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' +else + (cd docs/docsite/; sphinx-intl update -w 0 -d rst/locales -p "$(POTDIR)" -l $(LANGUAGES)) +endif + +needs-translation: +ifeq ($(LANGUAGES),) + @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' +else + (cd docs/docsite/; sphinx-intl stat -d rst/locales -l $(LANGUAGES) | grep -E ' [1-9][0-9]* (fuzzy|untranslated)' | sort) +endif + +htmldocs: ansible_structure generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html + +core_htmldocs: core_structure core_generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html + +singlehtmldocs: ansible_structure generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml + +core_singlehtmldocs: core_structure core_generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml + +# Note: The linkcheckdocs and htmlsingle targets depend on gettext_structure +# because that one does not exclude any rst files in its conf.py. +linkcheckdocs: gettext_structure generate_rst + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck + +htmlsingle: assertrst gettext_structure + sphinx-build -j $(CPUS) -b html -d $(BUILDDIR)/doctrees ./rst $(BUILDDIR)/html rst/$(rst) + @echo "Output is in $(BUILDDIR)/html/$(rst:.rst=.html)" + +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 "Cleaning 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/ $(EXTRA_COLLECTION_META_ARGS) ../../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 $(EXTRA_CLI_DUMPER_ARGS) ../../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 $(EXTRA_KEYWORD_DUMPER_ARGS) + +config: ../templates/config.rst.j2 + $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ $(EXTRA_CONFIG_DUMPER_ARGS) ../../lib/ansible/config/base.yml + +plugins: + $(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS) + +# This only builds the plugin docs included with ansible-core +core_plugins: + $(PLUGIN_FORMATTER) core -o rst $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS) + +testing: + $(TESTING_FORMATTER) + +epub: + (CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub) diff --git a/docs/docsite/Makefile.sphinx b/docs/docsite/Makefile.sphinx new file mode 100644 index 0000000..3bae705 --- /dev/null +++ b/docs/docsite/Makefile.sphinx @@ -0,0 +1,26 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXCONFDIR = rst +LANGOPTS ?= +SPHINXOPTS ?= -j $(CPUS) -n -w rst_warnings -c "$(SPHINXCONFDIR)" $(LANGOPTS) +SPHINXBUILD = sphinx-build +SPHINXPROJ = sdfsdf +SOURCEDIR = rst + +# Sets the build output directory if it's not specified on the command line +ifndef BUILDDIR + BUILDDIR = _build +endif + +# Put it first so that "make" without argument is like "make help". +help: + $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile.sphinx + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile.sphinx + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |