Commit graph

120 commits

Author SHA1 Message Date
Toshio Kuratomi
9dda393d70
Collections docs generation (#59761)
* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.
2020-07-17 13:07:35 -07:00
Brian Coca
062e780a68
starting metadata sunset (#69454)
* starting metadata sunset

 - purged metadata from any requirements
 - fix indent in generic handler for yaml content (whey metadata display was off)
 - make more resilient against bad formed docs
 - removed all metadata from docs template
 - remove metadata from schemas
 - removed mdata tests and from unrelated tests

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Rick Elrod <rick@elrod.me>
2020-06-04 21:01:46 -04:00
Matt Martz
4c4406b2df
Flatten the directory hierarchy of modules (#68966)
* Flatten the directory hierarchy of modules

* Update ignore.txt, flatten units

* Update imports

* Completely flatten the modules directory

* Update sanity ignore

* Fix some sanity test ignores

* Fix relative import

* Fix docs builds without category

* ci_complete

* Clean up docs. ci_complete

* Adjust needs/file alias

* ci_complete

* fix hardcoded ping module paths

Co-authored-by: Matt Davis <mrd@redhat.com>
2020-05-13 19:14:53 -07:00
Felix Fontein
fd43619f1a
Docs: improve anchors vs. header bar (#67244) 2020-02-11 13:16:26 -05:00
Dick Visser
5b93a14a0f
Add anchor to each parameter row (#66895)
* Add anchor to each paramater row

* Update docs/templates/plugin.rst.j2

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Insert full keys into plugin docs.

* Added visible links.

Co-authored-by: Felix Fontein <felix@fontein.de>
2020-02-03 20:11:48 +01:00
Abhijeet Kasurde
2728c2476e
docs: Fixed "Edit on GitHub" link for plugin, cli (#66745)
Fixed sphinx theme to navigate "Edit on Github" link to locate correct
plugin, cli source in GitHub repo.

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2020-01-30 10:55:46 -05:00
Sandra McCann
80dff8743a fixed some broken links (#66182) 2020-01-06 10:24:07 -06:00
Toshio Kuratomi
9973121f44 Fix ansible-galaxy man page generation (#65478)
The Action list was misformatted, leading to an error message in the man
page.

https://bugzilla.redhat.com/show_bug.cgi?id=1717110
2019-12-04 13:49:21 -06:00
Jordan Borean
f8f7662850
Add the ability to ignore files and collection build (#64688) 2019-11-14 05:02:58 +10:00
Felix Fontein
054285c34c crypto modules: improve return value list documentation (#62929)
* Improve return value documentation by allowing entry for return values.
* Add docs formatting, adjust styling.
* Fix sample return value. (Taken from https://tools.ietf.org/html/rfc7517#appendix-A.1.)
* Work around abuse of .
2019-10-11 13:59:15 -05:00
Sandra McCann
7badeb6df0 [docs] split collections into user and dev guide sections (#62363)
* split collections into user and dev guide sections

* sentence case
2019-09-19 15:09:19 -05:00
Jordan Borean
bf5b6695ec Add hint for config option priority (#62463)
* Add hint for config option priority

* Fix some spelling issues
2019-09-18 16:36:08 -04:00
Sorin Sbarnea
179eb623d7 docs: avoid confusing double negation (#62143)
Avoid "no backward incompatible interface" term which uses a double
negation and replaces it with easier "backward compatible interface"
contruct.
2019-09-11 11:26:22 -04:00
Spencer
21892aaf51 Correct grammar of contribute-message in footer. (#61414)
Adds a comma to the "you can edit this documentation" message in the footer on every documentation page.
2019-08-28 11:41:07 -05:00
Toshio Kuratomi
d9b3af523b Galaxy meta docs table (#60171)
* Use an rst table instead of a raw html table

* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
  extraneous whitespace in the URL

* Normalize description data before sending them to the templates
2019-08-13 15:00:13 -05:00
Ganesh Nalawade
127bd67f6e
Render elements in module doc and sanity test for sub-options (#59244)
* Render elements in module doc and sanity test for suboptions

*  Add support to render module elements value in ansible-doc output
   module html
*  Add validate-module sanity test of sunoptions.

* Add current validate module failures to ignore list

* Fix CI failure

* fix rebase conflict

* Fix CI issues

* Fix review comments

* Add validate-modules failure in ignore list
2019-07-30 12:07:21 +05:30
Jordan Borean
65049620ee
Generate galaxy.yml based on single source of truth (#59170)
* Generate galaxy.yml based on single source of truth

* Fix up tests and align file names

* Minor Makefile tweak

* Remove link in galaxy.yml file and make it a template file

* Moved collections docs to dev_guide

* change Makefile clean path

* Added readme to example meta file

* review fixes

* Use newer style for doc generation script

* Fix mistake in dev_guide index

* removed uneeded file, fixed links and added preview banner

* Moved banner for sanity test
2019-07-23 06:50:46 +10:00
Toshio Kuratomi
019d078a5a
Move common build code from _build_helpers (#55986)
We have some common code used by several docs scripts.  Migrate that
into the build-only shared code repository.

* Move lib/ansible/utils/_build_helpers.py to the directory for common
  build code
* Migrate docs/bin/dump_config.py to a build-ansible subcommand
* Migrate dump_keywords to the build-ansible framework
  * Make the script more maintainable by using functions and good
    variable names
  * Port to Python3 idioms
  * Fix bug so that private attributes will be undocumented
* Move generate_man to a build-ansible subcommand
* Port plugin_formatter to a build-ansible subcommand
* Rework command_plugins so that docs scripts can target Python-3.4+ and
  releng-only subcommands can use more recent versions of Python.
  The architecture is now that command_plugins/* need to be importable
  on Python-3.4.  The init_parsers() method needs to run on Python-3.4.
  But the main() method can utilize features of more recent Python as
  long as it fits within those parameters.
* Update docs build requirements

Port the plugin_formatter to build-ansible framework
2019-07-16 12:19:01 -07:00
Jordan Borean
b6791e6ae3
ansible-galaxy: add collection sub command (#57106)
* ansible-galaxy: add collection init sub command

* Fix changelog and other sanity issues

* Slim down skeleton structure, fix encoding issue on template

* Fix doc generation code to include sub commands

* Added build step

* Tidy up the build action

* Fixed up doc changes and slight testing tweaks

* Re-organise tests to use pytest

* Added publish step and fixed up issues after working with Galaxy

* Unit test improvments

* Fix unit test on 3.5

* Add remaining build tests

* Test fixes, make the integration tests clearer to debug on failures

* Removed unicode name tests until I've got further clarification

* Added publish unit tests

* Change expected length value

* Added collection install steps, tests forthcoming

* Added unit tests for collection install entrypoint

* Added some more tests for collection install

* follow proper encoding rules and added more tests

* Add remaining tests

* tidied up tests and code based on review

* exclude pre-release versions from galaxy API
2019-07-10 05:47:25 +10:00
Brian Coca
c2469648e4 Docs on general precedence (#50201)
* Add docs/docsite/rst/reference_appendices/general_precedence.rst

Co-Authored-By: Sandra McCann <samccann@redhat.com>
2019-07-09 12:14:40 -05:00
Alicia Cozine
fc94d79c47
CLI docs include license not copyright (#56871) 2019-05-23 14:53:07 -05:00
Sandra McCann
f9b43a0f68 Copyright fix for 2018 (#56860)
* update copyright in footer

* remove extraneous copyright from cli commands
2019-05-23 13:10:22 -05:00
Lindsay Hill
53ed1bfc49 Improve rendering of default lists (#56041) 2019-05-07 10:35:36 -05:00
Matt Martz
db6cc60352
Migrate command line parsing to argparse (#50610)
* Start of migration to argparse

* various fixes and improvements

* Linting fixes

* Test fixes

* Fix vault_password_files

* Add PrependAction for argparse

* A bunch of additional tweak/fixes

* Fix ansible-config tests

* Fix man page generation

* linting fix

* More adhoc pattern fixes

* Add changelog fragment

* Add support for argcomplete

* Enable argcomplete global completion

* Rename PrependAction to PrependListAction to better describe what it does

* Add documentation for installing and configuring argcomplete

* Address rebase issues

* Fix display encoding for vault

* Fix line length

* Address rebase issues

* Handle rebase issues

* Use mutually exclusive group instead of handling manually

* Fix rebase issues

* Address rebase issue

* Update version added for argcomplete support

* -e must be given a value

* ci_complete
2019-04-23 13:54:39 -05:00
Felix Fontein
395d471065 Docs: adding stub page for module/plugin aliases (#54448)
* Adding stub pages for deprecated module/plugin aliases.
2019-04-16 11:37:28 -05:00
Brian Coca
2c63f453be add info about relative paths to config page (#51351)
* add info about relative paths to config page

* Update docs/templates/config.rst.j2

Co-Authored-By: bcoca <bcoca@users.noreply.github.com>

* escape the macro to show the macro

* break up long line, revise
2019-02-21 13:21:28 -06:00
Dag Wieers
49afb3da34 Update Docsite edit (#51115)
* Improved template for docsite edits
2019-01-29 14:28:16 -05:00
Sandra McCann
3eec7f1820 Modules tocfix (#51077)
define & create subcategories, output by category and subcat
2019-01-23 13:21:23 -06:00
Felix Fontein
4c473ecef4 Sort suboptions and subresults in docs. (#50315)
Fixes #50041.
2019-01-02 15:40:44 -06:00
Dag Wieers
76450fd1c2
Docs: Show parameter types (in purple) (#49966)
* Docs: Show parameter types (in purple)

* Changes based on feedback

* Remove leftover statement after review

* Simplify TOC and support section

* Add missing 'v' to version_added

* Remove the v for version

* Update docs/templates/plugin.rst.j2

Co-Authored-By: dagwieers <dag@wieers.com>

* Update docs/templates/plugin.rst.j2

Co-Authored-By: dagwieers <dag@wieers.com>

* Move Author into Support section

* Avoid more "isn't included in any toctree" errors

* Add Red Hat support section, list module status
2018-12-20 18:34:32 +01:00
Dag Wieers
653c3da500 Fix document references in modules (#49892)
* Docs: Fixes internal module reference syntax for seealso
* Updates anchors and links
* Updates seealso in the docs for module **win_chocolatey**.
2018-12-17 10:20:06 -06:00
Dag Wieers
baf0ad2309 Docs: Add a "seealso" section to the module docs (#45949)
* Docs: Add a separate  "seealso" section to the module docs
to list related modules and/or related references. This clears up the notes
section for things that are actual notes.

So you can add a section in your module documentation and four types of
references are possible.

    seealso:

    # Reference by module name
    - module: aci_tenant

    # Reference by module name, including description
    - module: aci_tenant
      description: ACI module to create tenants on a Cisco ACI fabric.

    # Reference by rST documentation anchor
    - ref: aci_guide
      description: Detailed information on how to manage your ACI infrastructure using Ansible.

    # Reference by Internet resource
    - name: APIC Management Information Model reference
      description: Complete reference of the APIC object model.
      link: https://developer.cisco.com/docs/apic-mim-ref/

This PR also includes:

- Implements ansible-doc support
- Implements schema support for the seealso options
- Updates to the development documentation
- Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
  - This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
- We fixed the possible suboption types (which was limited to 'bool' only)

* Use latest stable instead of devel docs
2018-12-12 14:19:58 -06:00
Pilou
7fd8d8d8c7 doc: fix link to ansible-config (#49597) 2018-12-06 10:00:48 -05:00
Brendan Good
475844d1ae Fix man page template typo. (#48585)
changed from 'direcotry' to 'directory'.
2018-11-13 11:46:11 +05:30
Jordan Borean
1599752f26 docs: add Support section for plugin types (#46520)
* docs: add Maintenance section for plugin types
* Added supported_by name in bold to match Status
2018-10-08 13:54:53 -05:00
Takashi Sugimura
069ba81386 remove unnecessary space (#46462)
kindly advised from jborean93
2018-10-04 10:47:31 +10:00
Toshio Kuratomi
30662bedad
Only print warning when ansible.cfg is actually skipped (#43583)
Only print warning when ansible.cfg is actually skipped

* Also add unittests for the find_ini_config_file function
* Add documentation on world writable current working directory
  config files can no longer be loaded from a world writable current
  working directory but the end user is allowed to specify that
  explicitly.  Give appropriate warnings and information on how.

Fixes #42388
2018-08-03 10:39:33 -07:00
Dag Wieers
1ab411229a Get rid of duplicate status statement (#42885)
If a module was in status "preview", but it was not "supported"
(core/network) the message about the module being "preview" would be
repeated.
2018-07-26 11:32:49 -05:00
Brian Coca
b21c7c0232 create default status for when not provided
* also updated text to be 'plugin friendly' vs hardcoding modules

(cherry picked from commit 341a0f7b035588557d35fc12164a0f4031c786fe)
2018-07-09 11:44:01 -04:00
Brian Coca
b6f2aad600 ignore ansible.cfg in world writable cwd (#42070)
* ignore ansible.cfg in world writable cwd
 * also added 'warnings' to config
 * updated man page template
2018-06-29 16:46:10 -07:00
Felix Fontein
fb0b804988 Documentation: add parameter types, and version_added for return values and facts (#41999)
* Add types for parameters.

* Add version_added for return facts and return values.
2018-06-28 12:26:14 -05:00
Felix Fontein
0752dc12b7 Documentation: show non-string non-iterable defaults for choices (#40212)
* Also marking non-string defaults.

* Adding list filter from #37517 to plugin_formatter.

* Simplifying list test.

* Redistribute imports
2018-06-27 22:31:47 -04:00
Toshio Kuratomi
ad2e8dd6d8 Changes to support building docs with old jinja2
This commit: fa5c0282a4 relied upon
features present in Jinja-2.10 and above.  The changes here allow us to
build the *rst* with older versions of jinja2.
2018-06-25 15:53:56 -07:00
Will Thames
50fe5dc090 Trim parameter documentation when generating docs (#38470)
While the HTML produced is perfectly valid, without the `trim` filter,
a lot of warnings are emitted (700 lines of warnings out of 2812 are
eliminated by this change)
2018-06-21 13:51:58 +02:00
Felix Fontein
9f84c09bf3 Changing example code block language from yaml to yaml+jinja. (#40365) 2018-06-07 16:12:09 -05:00
Brian Campbell
fa5c0282a4 Use colspan on td instead of divs for hierarchical tables (#39948)
Address Firefox table-rendering issues in docs. Refactor to use colspan to provide table cells which can vary in width and indentation; the outermost has the greatest colspan, and each nested key has a colspan of one less than the parent, with padding cells for indentation.
Apply styling to table cells to get the table height to work without hacks or browser-specific
styling.  Simplify the markup and CSS by removing extra divs. Use two passes over the options, return values, and return facts in the Jinja2 module-docs template: one to determine the maximum nesting depth to compute the maximum colspan needed, plus one to lay out the rows.
2018-05-31 12:58:33 -05:00
Toshio Kuratomi
7ce1afebf0 Namespace the aliases ref target by plugin type (#38925) 2018-05-30 03:26:25 -04:00
Pilou
3f5f5faec6 doc: config intro, add link to searched locations (#39614) 2018-05-25 00:29:29 -04:00
Felix Fontein
f16933492d Fix problems in documentation generation (#40050)
* Treat C(...) as inline literal (as opposed to interpreted text).

* Making test for true and false more precise, to avoid matching 1, 1.0, etc.

* The 'is sameas' test already takes care of definedness.
2018-05-15 16:19:04 +02:00
Alicia Cozine
c8a9b411bc
Last docs link fixes (#39391)
* should not need <>, but fails without

* adds anchor to keywords page, uses it on plugins pages

* fixes envvar link errors

* harmonize file name and ref name as python_3

* removes undefined-lable from ignore list
2018-04-27 13:21:39 -05:00