Move man pages generations to rst2man (#37861)

pull/37974/head
Joseph Herlant 6 years ago committed by scottb
parent 02f44176b9
commit 00a7ff7974

@ -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

@ -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:

@ -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:
<http://docs.ansible.com>.

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

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

@ -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

@ -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

Loading…
Cancel
Save