diff options
| author | Adrian Likins <alikins@redhat.com> | 2017-09-07 15:44:20 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2017-09-07 15:44:20 -0400 |
| commit | 89c973445c6bbb08551703917a4eec6e484a3e0c (patch) | |
| tree | 44b97c2d3d83b47cffd0e22cea3f033accc79e07 /Makefile | |
| parent | 4a73390823bfe0f1bc6c1a548bb77e9af07e4673 (diff) | |
| download | ansible-89c973445c6bbb08551703917a4eec6e484a3e0c.tar.gz | |
generate rst doc pages for command line tools (#27530)
* 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 on
https://github.com/alikins/ansible/commit/6e34ea62429c417939bd96b6de5bf7e6ab1ff765 and
https://github.com/alikins/ansible/commit/a3afc785357878da354e21a709cf3b9f16c3f146
* 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>`
Diffstat (limited to 'Makefile')
| -rw-r--r-- | Makefile | 6 |
1 files changed, 4 insertions, 2 deletions
@@ -29,6 +29,7 @@ ASCII2HTMLMAN = a2x -L -D docs/html/man/ -d manpage -f xhtml else ASCII2MAN = @echo "ERROR: AsciiDoc 'a2x' command is not installed but is required to build $(MANPAGES)" && exit 1 endif +GENERATE_CLI = docs/bin/generate_man.py PYTHON=python SITELIB = $(shell $(PYTHON) -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") @@ -343,8 +344,9 @@ webdocs: .PHONY: generate_asciidoc generate_asciidoc: lib/ansible/cli/*.py - mkdir -p ./docs/man/man1/ - PYTHONPATH=./lib ./docs/bin/generate_man.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 make $(MANPAGES) |