Commit graph

23 commits

Author SHA1 Message Date
Brian Coca
afc460c943 tollerate 'string' descriptions 2017-11-14 11:18:48 -05:00
Toshio Kuratomi
e07cbb033f Keywords docs (#32807)
* Fixup keyword dumping

* Clarify introductory text
* Turn links in the keyword description into seealso entries in the rst.

* Have plugin_formatter cleanup trailing whitespace

The indent filter in jinja2 < 2.10 indents blank lines by default which
leads to trailing whitespace.  Cleanup after that filter.

* Edits

* Copy edit
2017-11-10 16:59:26 -08:00
Ed Santiago
47fb002c88 (minor) fix broken link, awkward phrasing (#32085)
* (minor) fix broken link, awkward phrasing

Simple transposition error was resulting in a link not
being properly htmlified.

Also clean up redundant 'this' and trailing whitespace.

Signed-off-by: Ed Santiago <santiago@redhat.com>

* Edits
2017-10-27 21:39:23 -07:00
Brian Coca
2ed46e04f4 more updates to plugin/config generation (#30787)
* fixed module generation

added missing lookup page
point to plugins when plugins
made modules singular
add display for verbose an debug messages
nicer templating, changed generation order for ref
corrected links
moved most of lookup docs to plugin section

* Copy edits
* Fixed typos
* Clarified wording
2017-10-11 00:15:25 -04:00
sduthil
15dffe04dd fix misformatted docsite link (#31384)
reason: The link is showing verbatim in the docs, where it should only
show "knowledge base article".

Also, generating the docs shows a lot of:

docs/docsite/rst/win_acl_module.rst:424: WARNING: Unknown target name: "know ledge base article<https://access.redhat.com/articles/rhel-top-support-policies>".
2017-10-05 18:52:30 -07:00
Brian Coca
b233f3f296 updated plugin docs (#30490)
* updated  docs

- for devs:
  - added inventory/vars section
  - made some updates to general section and other plugin types
- for users:
 - added 'user' plugin section to start describing the plugins
 - docs on types, what they are and how to use

- removed ref to deleted AUTHORS file
- corrected several typos/headers
- added descriptions to config.rst template
- ignore generated files for cli/plugins and config
- remove new generated files on `make clean`
- moved details from devguid and intro doc to plugin specific pages
- pretied up lookup notes
- changed precedence ref to not conflict config
- removed duplicate config data, as config is autogenerated and up to date
- put new plugins under playbooks
- added `pass` cause rst/python dislikes fractions
- removed dupe in .gitignore, alpha sorted to avoid moar dupes
- added try cause rst/python freaks out

* generate plugins into their own dir

only do plugins that support docs
use toctree from main plugins page
2017-09-22 23:19:50 -04:00
Adrian Likins
da15cf1f54 Generate plugin rst (#28901)
Generate rst docs for plugins 

Based on rst generated for modules. But generated plugin
docs go into docs/docsite/rst/plugins/$PLUGIN_TYPE/plugin_name.rst
( docs/docsite/rst/plugins/connection/ssh.py for ex)

* move plugins docs to rst/*_plugins/ subdirs for namespace
* Only gen support pages for modules for now.
* Add generated plugin docs to gitignore* add list_*_plugins templates
* support MODULES/PLUGINS filters for make htmldocs

   Add a 'PLUGINS=ssh' filter env var like MODULES to filter plugins to build docs for.

* fixup 'historical' version_added, skip plugins/loader.py
* Fix plugins_by_support ref link to new plugins/*/ location
* use :ref: for common_return_values, allow empty version_added
* warnings on missing doc info
* add a prefix to _random_choice
  It was colliding with the target for random_choice plugin
2017-09-19 11:14:27 -04:00
Adrian Likins
52f2edf19d change generated playbooks_keywords.rst to use an rst 'glossary' (#28843)
* Use a rst glossary for playbooks_keywords docs
* Add a 'Task' and 'Tasks' to glossary.
* Update keywords desciptions,
* use :term: rst ref, some quoting
* Make it more obvious that 'retries' and 'until' need to be used in combination.
2017-09-07 15:46:53 -04:00
Adrian Likins
89c973445c 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
6e34ea6242 and
a3afc78535

* 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>`
2017-09-07 15:44:20 -04:00
Adrian Likins
596dc8c442 Add ANSIBLE_CONFIG envvar to config/envvars tmpl (#28886) 2017-09-01 14:53:42 -07:00
Adrian Likins
8035e68d44 Generate a rst for config and env options from base.yml (#28739)
* wip, gen docs from config/base.yml

* wip

* dont change conf.py here

* cleanup, add dump_config --template-file cli opt

* some desc are string, some are lists...

TODO: fix base.yml so it is consistent

* Filter out TODO and empty descriptions
2017-08-31 10:11:05 -04:00
Toshio Kuratomi
40ea448c7b Misc docs fixes
* Revise and link inline to the lists of modules

* Fix jinja2 objects.inv fallback path

* Fix bolding of deprecation marker

* Change module_support to link to lists via :doc:
  That links to the top of the page instead of a section.

* Add a short text for each list of maintained modules
* Change maintenance info to only display on core and network modules
2017-08-22 11:52:30 -07:00
Jiri Tyr
5660b18b6a Adding missing period into the module doc template 2017-08-21 14:20:08 -04:00
Andreas Maier
b900f4a3be Fixed return table in module docs generated by plugin_formatter.py (#25329) (#25330)
This change fixes two issues with the generated return table:

1. When specifying a list of strings in the 'description' field of a
   return value, it shows them in Python list syntax on the resulting
   web page, e.g. `['a', 'b', 'c']`.
2. When specifying more than one line for the 'sample' field, the
   result table gets damaged in the HTML output.

In addition, this change re-arranges the HTML tags produced in the
generated RST file such that they line up nicely and can better be
checked by humans for completeness.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>
2017-08-18 15:38:55 -04:00
Toshio Kuratomi
546187a8af Revamp the plugin_formatter doc generator
* Use a template to generate the category lists
* Refactor so that we first extract all of the data that we need to
  build the docs and then give that data to the templates to build with
* Add docs page listing modules ordered by support level
2017-08-15 23:12:08 -07:00
Toshio Kuratomi
af2073d057 metadata 1.1
* Add network value to support_by field.
* New support_by value, certified
* Deprecate curated in favor of certified
* Add conversion from 1.0 to 1.1 to metadata-tool
* Add supported by Red Hat field to ansible-doc output
2017-08-15 23:12:08 -07:00
John R Barker
f338dd2fc3 Render returned dictionaries Fixes #24775 (#24777)
plugin.rst.j2 was out of sync with syntax validator
2017-05-18 15:13:33 +01:00
John R Barker
ecbf8e933a Docs how to test (2nd) (#24094)
* Big testing doc refactor
* Combine all the testing documentation in to one place to make it easier to find
* Convert everything to RST
* Create testing_network guide
* Create testing landing page
* For each section detail "how to run" and "how to extend testing"
* More examples
* Lots more detail
2017-04-28 09:08:26 +01:00
Brian Coca
a0a26700c9 remove author as it dupes 2017-03-30 12:36:52 -04:00
Brian Coca
da045a9c1f more info for asciidoc to correctly build manpages 2017-03-30 12:34:46 -04:00
Brian Coca
18a7a1ec31 added docs to CLI docstringsadded
removed 'now intermediate build files' from repo
adjusted gitignore
2017-03-24 15:52:36 -04:00
Brian Coca
424e1946f4 moved docs generation and templates to docs/ 2017-03-24 15:52:36 -04:00
Brian Coca
b4c47ebf68 draft to generate man pages 2017-03-24 15:52:36 -04:00