mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
89c973445c
* let generate_man also gen rst pages for cli tools * make template-file, output-dir, output format cli options for generate_man * update main Makefile to use generate_man.py for docs (man pages and rst) * update vault docs that use :option: * Edits based on6e34ea6242anda3afc78535* add a optparse 'desc' to lib/ansible/cli/config.py The man page needs a short desc for the 'NAME' field which it gets from the option parse 'desc' value. Fixes building ansible-config man page. * add trim_docstring from pep257 to generate_man use pep258 docstring trim function to fix up any indention weirdness inherit to doc strings (ie, lines other than first line being indented. * Add refs to cli command actions To reference ansible-vaults --vault-id option, use: :option:`The link text here <ansible-vault --vault-id>` or: :option:`--vault-id <ansible-vault --vault-id>` To reference ansible-vault's 'encrypt' action, use: :ref:`The link text here <ansible_vault_encrypt>` or most of the time: :ref:`ansible-vault encrypt <ansible_vault_encrypt>`
83 lines
2.8 KiB
Makefile
83 lines
2.8 KiB
Makefile
OS := $(shell uname -s)
|
|
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"):
|
|
FORMATTER=../bin/plugin_formatter.py
|
|
TESTING_FORMATTER=../bin/testing_formatter.sh
|
|
DUMPER=../bin/dump_keywords.py
|
|
CONFIG_DUMPER=../bin/dump_config.py
|
|
GENERATE_CLI=../bin/generate_man.py
|
|
ifeq ($(shell echo $(OS) | egrep -ic 'Darwin|FreeBSD|OpenBSD|DragonFly'),1)
|
|
CPUS ?= $(shell sysctl hw.ncpu|awk '{print $$2}')
|
|
else
|
|
CPUS ?= $(shell nproc)
|
|
endif
|
|
|
|
assertrst:
|
|
ifndef rst
|
|
$(error specify document or pattern with rst=somefile.rst)
|
|
endif
|
|
|
|
all: docs
|
|
|
|
docs: clean htmldocs
|
|
|
|
htmldocs: testing keywords modules staticmin cli config
|
|
|
|
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
|
|
|
|
webdocs: docs
|
|
|
|
#TODO: leaving htmlout removal for those having older versions, should eventually be removed also
|
|
clean:
|
|
-rm -rf htmlout
|
|
-rm -rf _build
|
|
-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 rst/list_of_*.rst
|
|
-rm rst/*_by_category.rst
|
|
-rm rst/*_module.rst
|
|
-rm rst/*_maintained.rst
|
|
-rm rst/playbooks_directives.rst
|
|
-rm rst/playbooks_keywords.rst
|
|
# -rm rst/cli/ansible*.rst
|
|
|
|
.PHONEY: docs clean
|
|
|
|
# TODO: make generate_man output dir cli option
|
|
cli: $(GENERATE_CLI)
|
|
PYTHONPATH=../../lib $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/ --output-format rst ../../lib/ansible/cli/*.py
|
|
|
|
keywords: $(FORMATTER) ../templates/playbooks_keywords.rst.j2
|
|
PYTHONPATH=../../lib $(DUMPER) --template-dir=../templates --output-dir=rst/ -d ./keyword_desc.yml
|
|
|
|
config:
|
|
PYTHONPATH=../../lib $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/ -d ../../lib/ansible/config/base.yml
|
|
|
|
modules: $(FORMATTER) ../templates/plugin.rst.j2
|
|
# Limit building of module documentation if requested.
|
|
ifdef MODULES
|
|
PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ -l $(MODULES)
|
|
else
|
|
PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/
|
|
endif
|
|
|
|
testing:
|
|
$(TESTING_FORMATTER)
|
|
|
|
staticmin:
|
|
cat _themes/srtd/static/css/theme.css | sed -e 's/^[ ]*//g; s/[ ]*$$//g; s/\([:{;,]\) /\1/g; s/ {/{/g; s/\/\*.*\*\///g; /^$$/d' | sed -e :a -e '$$!N; s/\n\(.\)/\1/; ta' > _themes/srtd/static/css/theme.min.css
|
|
|
|
epub:
|
|
(CPUS=$(CPUS) make -f Makefile.sphinx epub)
|
|
|
|
htmlsingle: assertrst
|
|
sphinx-build -j $(CPUS) -b html -d _build/doctrees ./rst _build/html rst/$(rst)
|
|
@echo "Output is in _build/html/$(rst:.rst=.html)"
|