From 00a7ff7974bf39314170e1d84c18f95d059eaa3c Mon Sep 17 00:00:00 2001 From: Joseph Herlant Date: Mon, 26 Mar 2018 16:28:28 -0700 Subject: [PATCH] Move man pages generations to rst2man (#37861) --- Makefile | 32 +++++++++++++++++--------------- docs/bin/generate_man.py | 6 +++--- docs/templates/man.j2 | 32 ++++++++++++++++---------------- packaging/arch/PKGBUILD | 2 +- packaging/debian/Dockerfile | 2 +- packaging/debian/README.md | 2 +- packaging/debian/control | 2 +- 7 files changed, 40 insertions(+), 38 deletions(-) diff --git a/Makefile b/Makefile index e1939271f7c..aa22fb3d172 100644 --- a/Makefile +++ b/Makefile @@ -21,12 +21,13 @@ PREFIX ?= '/usr/local' # This doesn't evaluate until it's called. The -D argument is the # directory of the target file ($@), kinda like `dirname`. -MANPAGES ?= $(patsubst %.asciidoc.in,%,$(wildcard ./docs/man/man1/ansible*.1.asciidoc.in)) -ifneq ($(shell which a2x 2>/dev/null),) -ASCII2MAN = a2x -L -D $(dir $@) -d manpage -f manpage $< -ASCII2HTMLMAN = a2x -L -D docs/html/man/ -d manpage -f xhtml +MANPAGES ?= $(patsubst %.rst.in,%,$(wildcard ./docs/man/man1/ansible*.1.rst.in)) +ifneq ($(shell which rst2man 2>/dev/null),) +ASCII2MAN = rst2man $< $@ +else ifneq ($(shell which rst2man.py 2>/dev/null),) +ASCII2MAN = rst2man.py $< $@ else -ASCII2MAN = @echo "ERROR: AsciiDoc 'a2x' command is not installed but is required to build $(MANPAGES)" && exit 1 +ASCII2MAN = @echo "ERROR: rst2man from docutils command is not installed but is required to build $(MANPAGES)" && exit 1 endif GENERATE_CLI = docs/bin/generate_man.py @@ -140,14 +141,15 @@ integration: authors: sh hacking/authors.sh -# Regenerate %.1.asciidoc if %.1.asciidoc.in has been modified more -# recently than %.1.asciidoc. -%.1.asciidoc: %.1.asciidoc.in +# Regenerate %.1.rst if %.1.rst.in has been modified more +# recently than %.1.rst. +%.1.rst: %.1.rst.in sed "s/%VERSION%/$(VERSION)/" $< > $@ + rm $< -# Regenerate %.1 if %.1.asciidoc or VERSION has been modified more -# recently than %.1. (Implicitly runs the %.1.asciidoc recipe) -%.1: %.1.asciidoc VERSION +# Regenerate %.1 if %.1.rst or VERSION has been modified more +# recently than %.1. (Implicitly runs the %.1.rst recipe) +%.1: %.1.rst VERSION $(ASCII2MAN) .PHONY: loc @@ -176,7 +178,7 @@ clean: find . -type f \( -name "*.swp" \) -delete @echo "Cleaning up manpage stuff" find ./docs/man -type f -name "*.xml" -delete - find ./docs/man -type f -name "*.asciidoc" -delete + find ./docs/man -type f -name "*.rst" -delete find ./docs/man/man3 -type f -name "*.3" -delete rm -f ./docs/man/man1/* @echo "Cleaning up output from test runs" @@ -345,13 +347,13 @@ epub: webdocs: (cd docs/docsite/; CPUS=$(CPUS) make docs) -.PHONY: generate_asciidoc -generate_asciidoc: lib/ansible/cli/*.py +.PHONY: generate_rst +generate_rst: lib/ansible/cli/*.py mkdir -p ./docs/man/man1/ ; \ PYTHONPATH=./lib $(GENERATE_CLI) --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py -docs: generate_asciidoc +docs: generate_rst make $(MANPAGES) .PHONY: alldocs diff --git a/docs/bin/generate_man.py b/docs/bin/generate_man.py index 3493ee355de..b2d5bfd4107 100755 --- a/docs/bin/generate_man.py +++ b/docs/bin/generate_man.py @@ -241,12 +241,12 @@ if __name__ == '__main__': if cli_name == 'adhoc': cli_class_name = 'AdHocCLI' # myclass = 'AdHocCLI' - output[cli_name] = 'ansible.1.asciidoc.in' + output[cli_name] = 'ansible.1.rst.in' cli_bin_name = 'ansible' else: # myclass = "%sCLI" % libname.capitalize() cli_class_name = "%sCLI" % cli_name.capitalize() - output[cli_name] = 'ansible-%s.1.asciidoc.in' % cli_name + output[cli_name] = 'ansible-%s.1.rst.in' % cli_name cli_bin_name = 'ansible-%s' % cli_name # FIXME: @@ -255,7 +255,7 @@ if __name__ == '__main__': cli_list = allvars.keys() - doc_name_formats = {'man': '%s.1.asciidoc.in', + doc_name_formats = {'man': '%s.1.rst.in', 'rst': '%s.rst'} for cli_name in cli_list: diff --git a/docs/templates/man.j2 b/docs/templates/man.j2 index c9a06994e8f..9ded1ec68fb 100644 --- a/docs/templates/man.j2 +++ b/docs/templates/man.j2 @@ -1,16 +1,15 @@ {% set name = ('ansible' if cli == 'adhoc' else 'ansible-%s' % cli) -%} -{{name}}(1) -{{ '=' * ((name|length|int) + 3) }} -:doctype: manpage -:encoding: utf-8 -:lang: en -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands +{{name}} +{{ '=' * ( name|length|int ) }} + +{{ '-' * ( short_desc|default('')|string|length|int ) }} +{{short_desc|default('')}} +{{ '-' * ( short_desc|default('')|string|length|int ) }} + +:Version: Ansible %VERSION% +:Manual section: 1 +:Manual group: System administration commands -NAME ----- -ansible{% if cli != 'adhoc' %}-{{cli}}{% endif %} - {{short_desc|default('')}} SYNOPSIS @@ -26,9 +25,9 @@ DESCRIPTION COMMON OPTIONS -------------- {% for option in options|sort(attribute='options') %} -{% for switch in option['options'] %}*{{switch}}*{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}:: +{% for switch in option['options'] %}**{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %} -{{ option['desc'] }} + {{ option['desc'] }} {% endfor %} {% endif %} @@ -48,11 +47,12 @@ ARGUMENTS ACTIONS ------- {% for action in actions %} - *{{ action }}*::: {{ (actions[action]['desc']|default(' '))|wordwrap}} +**{{ action }}** + {{ (actions[action]['desc']|default(' '))}} {% if actions[action]['options'] %} {% for option in actions[action]['options']|sort(attribute='options') %} -{% for switch in option['options'] if switch in actions[action]['option_names'] %}*{{switch}}*{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}:: +{% for switch in option['options'] if switch in actions[action]['option_names'] %}**{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %} {{ (option['desc']) }} {% endfor %} @@ -116,7 +116,7 @@ Ansible is released under the terms of the GPLv3 License. SEE ALSO -------- -{% for other in cli_list|sort %}{% if other != cli %}*ansible{% if other != 'adhoc' %}-{{other}}{% endif %}*(1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %} +{% for other in cli_list|sort %}{% if other != cli %}**ansible{% if other != 'adhoc' %}-{{other}}{% endif %}** (1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %} Extensive documentation is available in the documentation site: . diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD index f9031bdf50b..abcc0a21ea0 100644 --- a/packaging/arch/PKGBUILD +++ b/packaging/arch/PKGBUILD @@ -17,7 +17,7 @@ arch=('any') url='https://www.ansible.com' license=('GPL3') depends=('python2' 'python2-paramiko' 'python2-jinja' 'python2-yaml') -makedepends=('git' 'asciidoc' 'fakeroot') +makedepends=('git' 'docutils' 'fakeroot') optdepends=('python2-pyasn1: needed for accelerated mode' 'python2-crypto: needed for accelerated mode' 'python2-keyczar: needed for accelerated mode') diff --git a/packaging/debian/Dockerfile b/packaging/debian/Dockerfile index 559dc8d5ce6..de831d09cf1 100644 --- a/packaging/debian/Dockerfile +++ b/packaging/debian/Dockerfile @@ -1,7 +1,7 @@ FROM ubuntu:xenial RUN apt-get update && apt-get install -y \ - asciidoc \ + python-docutils \ cdbs \ debootstrap \ devscripts \ diff --git a/packaging/debian/README.md b/packaging/debian/README.md index 74fc3a4cb95..7eaa4721395 100644 --- a/packaging/debian/README.md +++ b/packaging/debian/README.md @@ -6,7 +6,7 @@ To create an Ansible DEB package: __Note__: You must run this target as root or set `PBUILDER_BIN='sudo pbuilder'` ``` -apt-get install asciidoc cdbs debootstrap devscripts make pbuilder python-setuptools +apt-get install python-docutils cdbs debootstrap devscripts make pbuilder python-setuptools git clone https://github.com/ansible/ansible.git cd ansible DEB_DIST='xenial trusty precise' make deb diff --git a/packaging/debian/control b/packaging/debian/control index b73c3125170..ed277b8a0dd 100644 --- a/packaging/debian/control +++ b/packaging/debian/control @@ -3,7 +3,7 @@ Section: admin Priority: optional Standards-Version: 3.9.3 Maintainer: Ansible, Inc. -Build-Depends: cdbs, debhelper (>= 5.0.0), asciidoc, python, dh-python | python-support, python-setuptools, lsb-release +Build-Depends: cdbs, debhelper (>= 5.0.0), python-docutils, python, dh-python | python-support, python-setuptools, lsb-release Homepage: http://ansible.github.com/ Package: ansible