Commit graph

18 commits

Author SHA1 Message Date
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