Move man pages generations to rst2man (#37861)

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

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:

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,7 +25,7 @@ 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'] }}
 {% endfor %}
@@ -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:
 <http://docs.ansible.com>.

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')

packaging/debian/Dockerfile

@@ -1,7 +1,7 @@
 FROM ubuntu:xenial
 
 RUN apt-get update && apt-get install -y \
-    asciidoc \
+    python-docutils \
     cdbs \
     debootstrap \
     devscripts \

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

packaging/debian/control

@@ -3,7 +3,7 @@ Section: admin
 Priority: optional
 Standards-Version: 3.9.3
 Maintainer: Ansible, Inc. <info@ansible.com>
-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