This change fixes bugs in the manpage generator that existed since it
was first added.
It exposes CLI `ARGUMENTS` value to manpage templates.
Before this change, the code contained a typo, causing the `for`-loop
iterate over individual characters of the `'ARGUMENTS'` string rather
than iterating over a tuple. A missing comma was at fault.
The updated code gets rid of the `for`-loop and conditionals since it
seems to have been a premature complexity increase and no other things
than `'ARGUMENTS'` were ever added into the broken iterable.
The functional change is that `arguments` is now always present in the
Jinja2 context, unlike being missing sometimes because of the previous
design (not that it was ever present, because of the bug! sigh...)
The Jinja2 templates perform an `{% if arguments %}` check, letting
the template engine silently ignore the missing variable. The clause
was always falsy, meaning that the arguments section was not included
in the manpages for at least the last 6 years. With this fix, it will
be.
This patch also deduplicates calling `opt_doc_list` @ generate_man.
It was called late in the execution, more times than necessary. This
patch makes sure it happens once by putting it at the top of the scope.
It fixes rendering library and inventory in manpages.
The corresponding Jinja2 templates have blocks wrapped with
conditionals like `{% if inventory %}` and `{% if library %}` but said
variables were never injected into the context, nor were they even
deduced on the Python side of the generator. This means that the
conditional clauses were always falsy, never showing the portions of
the manpages.
The Python script has hints for how the `inventory` variable was to be
calculated, which is confirmed through the Git paleontology efforts.
The block of code that references to the `inventory` bit was
incorrectly checking a variable with a list of nested objects for the
presence of a string which was never going to work.
This patch fixes this check by verifying the CLI flag against the
correct variable containing a list of options and exposes it to the
Jinja2 templates.
It also exposes the `library` variable in a similar way.
The block displaying other binaries in Sphinx CLI docs has been
synchronized with the manpage template.
Previously, the current binary was displayed also. This patch gets rid
of the unwanted trailing comma there too.
Finally, the CLI executables list in the manpage template now reuses
the same variable as the RST template that doesn't need any
post-processing in Jinja2.
Before, it was already used in the RST template so this patch aligns
both templates to use the same logic as they got out-of-sync over time.
PR #80450.
(cherry picked from commit a84b3a4e72)
Co-authored-by: Sviatoslav Sydorenko <webknjaz@redhat.com>
* [stable-2.14] Remove docs dir dependency from man page build (#81003)
(cherry picked from commit b3f1290bcd)
Co-authored-by: Matt Clay <matt@mystile.com>
* Update path in Makefile
* Update special_variables.rst (#80210)
The usage of a glossary on this page will allow linking to a specific special variable, like on the glossary page, e.g.: https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html#term-Idempotency
(cherry picked from commit 1491ec8019)
* uri: improve force_basic_auth documentation (#80211)
Add more details about what "true" and "false" mean for the
force_basic_auth setting. Give example scenarios when clients may want
to use this setting.
(cherry picked from commit fc8203168e)
* Improve dirname and basename filter doc (#80054)
(cherry picked from commit 93beef053e)
* Move Collection requirements to ansible/ansible (#80234)
(cherry picked from commit cba3952434)
* Add Ansible community 7.4.0 porting guide (#80338)
(cherry picked from commit 29e0a68af2)
* Add antsibull-changelog and antsibull-docs to other tools and programs page. (#80340)
(cherry picked from commit cf44c84396)
---------
Co-authored-by: Benoît Geeraerts <10222438+b-enoit-be@users.noreply.github.com>
Co-authored-by: Ken Dreyer <kdreyer@redhat.com>
Co-authored-by: Daniel Ziegenberg <daniel@ziegenberg.at>
Co-authored-by: Anwesha Das <anwesha@das.community>
Co-authored-by: Felix Fontein <felix@fontein.de>
* improve doc dependency install steps (#80120)
(cherry picked from commit 352010f9c3)
* docs: automatic `always` tag in gather_facts (#80052)
(cherry picked from commit 3216e071c7)
* docsite requirements path (#80134)
(cherry picked from commit 1055803c3a)
* Adjust release schedule docs to four weeks (#80166)
(cherry picked from commit 7ce951ff48)
* Fix spelling and grammar in subelements filter doc (#80137)
(cherry picked from commit 12c1891ce6)
* Fixed typo (#80184)
`uvault` should be `unvault`
(cherry picked from commit cb2180e286)
* Document debugging conditionals (#80239)
##### SUMMARY
Add a section to the docs describing how to debug conditional statements - how to get Ansible to show you whether your `when:` clause evaluates to `true` or `false`.
I ran into trouble with this and couldn't find anything in the docs. Thought I'd add it.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
(cherry picked from commit 507fd1bd60)
* Update connection.rst (#80194)
(cherry picked from commit 0937cc4862)
---------
Co-authored-by: Don Naro <dnaro@redhat.com>
Co-authored-by: Jairo Llopis <973709+yajo@users.noreply.github.com>
Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com>
Co-authored-by: Zachary Peschke <8718570+zpeschke@users.noreply.github.com>
Co-authored-by: Harmdhast <pandemonium.harmdhast@gmail.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Esther Christopher <estheradamuchris@gmail.com>
This change allows ansible-test to work with newer versions of git on AZP..
(cherry picked from commit bad8843124)
Co-authored-by: Matt Clay <matt@mystile.com>
* Add Steampunk Spotter to Other tools list (#80006)
(cherry picked from commit 122de95d85)
* Clarify combine filter examples (#80078)
(cherry picked from commit 39fd899d83)
* Add Ansible community 7.3.0 porting guide (#80106)
(cherry picked from commit dbcaab1012)
* Clarify when plugin settings are being populated (#79710)
(cherry picked from commit 998b5c1a06)
* Update playbooks_tests.rst (#79788)
(cherry picked from commit ed879954f9)
* consistent booleans for page text and code blocks (#80036)
* consistent booleans for page text and code blocks
* Update check_mode from n to false
(cherry picked from commit 940fdf5dba)
* Update collection_integration_updating.rst (#80037)
(cherry picked from commit ce5471fc9f)
* package_facts requires python-rpm on SUSE systems in ansible 2.12.1 (#80041)
(cherry picked from commit 43aa47c2af)
* fix: jinja complex type transforms doesn't work as documented (#80067)
jinja complex type transforms: dict(somelist| slice(2)) doesn't work as documented. Changed the example to use zip_longest
(cherry picked from commit 5ad77fc7bb)
* Docs: Clarify note on tags (#80079)
The current wording could be read as "tasks that are tagged *both* configuration and packages" while in fact it is "tasks that are tagged *either* configuration *or* packages"
(cherry picked from commit 563833d124)
* Fix typo docs in playbooks_tags.rst (#80117)
(cherry picked from commit c8f740cfee)
* Encourage true/false for module documentation (#80060)
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 02c49ffe60)
* fix link for development guidelines (#80055)
(cherry picked from commit 012393e2cd)
* improve password lookup syntax in examples (#80092)
(cherry picked from commit 809727a7c7)
* Fixing typos (#80045)
(cherry picked from commit 841b71c94f)
* clarify playbook tests (#80073)
(cherry picked from commit 0521184337)
* Update playbooks_conditionals.rst (#80062)
"changed" was missing from the docs
(cherry picked from commit cc8e6d06d0)
---------
Co-authored-by: Anže Luzar <aluzarwork@gmail.com>
Co-authored-by: Klaus Frank <agowa338@users.noreply.github.com>
Co-authored-by: Anwesha Das <anwesha@das.community>
Co-authored-by: nkakouros <tterranigma@gmail.com>
Co-authored-by: Gijikiki <61326640+Gijikiki@users.noreply.github.com>
Co-authored-by: Aastha Varma <aastha.code@gmail.com>
Co-authored-by: Player256 <92082372+Player256@users.noreply.github.com>
Co-authored-by: Desmond Obisi <51109125+DesmondSanctity@users.noreply.github.com>
Co-authored-by: Raphael Michel <mail@raphaelmichel.de>
Co-authored-by: Nicolas P <0kyn.dev@gmail.com>
Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com>
Co-authored-by: Akira Yokochi <akira6592@gmail.com>
Co-authored-by: Andreas Deininger <andreas@deininger.net>
Co-authored-by: Keeper-of-the-Keys <es.rosenberg+github@gmail.com>
* [Docs] add easyfix/good first issue/docs links (#79830)
(cherry picked from commit 722fc05c31)
* [Docs] add doc links to documentation_contributions.rst (#79840)
(cherry picked from commit 58f0950638)
* Remove dev_guide stubs (#79795)
* Remove dev_guide stubs
* Remove Cisco ACI Dev Guide
(cherry picked from commit 10f0e5f6d4)
* maintainers_guidelines.rst: add a link to collection release guidelines (#79859)
(cherry picked from commit fa382670dc)
* Mentions 'meta: flush_handlers' task (#79542)
(cherry picked from commit d8dc76e134)
* Description for changing User ID to match user value (#79470)
(cherry picked from commit 913e4863af)
* Remove irrelevant line (#79865)
Remove irrelevant comment line form example code
(cherry picked from commit 1c01eab3fb)
---------
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: Mario Lenz <m@riolenz.de>
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: JaroslavKlech <klechh@gmail.com>
Co-authored-by: Tabah Baridule M <dulemartins07@gmail.com>
Co-authored-by: Konrad Gawda <konrad.gawda.opensource@gmail.com>
* fix filename for sidecar docs (#79779)
(cherry picked from commit f2707d1fbc)
* correct examples to use removed_from_collection not collection_name (#79803)
(cherry picked from commit 7ab3de7ee8)
* Fix: documentation for per-task timeout (#79715)
(cherry picked from commit 48e6bf8d27)
* [Docs] maintainers_guidelines: add WG and real-time chat request info (#79750)
(cherry picked from commit 6cb6d655b3)
* doc fix for platform content #79794 (#79801)
(cherry picked from commit d7a4152851)
* Expand docs for the import sanity test. (#79768)
* Expand docs for the import sanity test.
* Remove note about Python 2.7 compat.
It should not be needed since there is a sanity test to enforce use of `__metaclass__ = type`.
* Improve introductory paragraph.
* Fix link typo.
(cherry picked from commit 2164d5699c)
* docs: Extend password entry of ansible.builtin.user (#79694)
* docs: Extend password entry of ansible.builtin.user
Clarify that `password` sets the password hash.
Not the actual password.
Fixes part of #79684
(cherry picked from commit 6cd1a1404a)
* Update dev_guide.rst (#79625)
(cherry picked from commit 65eb5c0a9f)
* Improve documentation on requirements.yml (#76140)
Makes it clear that user can use range identifiers with collection
versions inside requirements.yml files.
(cherry picked from commit 44dcfde9b8)
---------
Co-authored-by: Evgeni Golov <evgeni@golov.de>
Co-authored-by: Jo <jo@swagspace.org>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: prasadpatil49 <51715670+prasadpatil49@users.noreply.github.com>
Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: Jens Timmerman <github@caret.be>
Co-authored-by: Sorin Sbarnea <ssbarnea@redhat.com>
* Update authentication.rst (#79623)
(cherry picked from commit e7af7532bd)
* Fix typo (#79641)
(cherry picked from commit 8e7cc371be)
* correct the mistake of example repeat_original (#79659)
there is a little mistake
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
(cherry picked from commit 6f8c1da0c8)
* switched reference from katacoda to instruqt (#79698)
(cherry picked from commit 0fc932fda0)
* contributor_path: fix typos (#79678)
(cherry picked from commit fe7d488a1b)
* Fix broken reference to FAQ (#79621)
(cherry picked from commit 602824db1d)
* Docsite: add Security Automation Working Group to Communication guide (#79692)
(cherry picked from commit 65efa4b97f)
* Docsite: remove dead Lockdown Working Group from Communication guide (#79693)
(cherry picked from commit 55f9d7f71f)
* Fix `undef()` example to a valid Jinja template (#79701)
(cherry picked from commit e41d2874a6)
* Truthy value should be one of false or true (#79730)
Otherwise ansible-lint complains: https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.truthy
(cherry picked from commit b756a08d89)
* Fix regex filter docs (#79736)
* Fix notes in regex_replace doc
The documentation says that this maps to 'regex.replace' when it should say 're.replace'. The distinction is important because of the third-party 'regex' module that has more features than the built-in 're' module. https://pypi.org/project/regex/
* Fix notes in re.search docs
The documentation says that this maps to 'regex.search' when it should say 're.search'. The distinction is important because of the third-party 'regex' module that has more features than the built-in 're' module. https://pypi.org/project/regex/
(cherry picked from commit cf50d8131f)
* complex_data_manipulation.rst: fix typo (#79758)
(cherry picked from commit b5b7f9bce2)
* Fix broken link for inventory script examples (#79762)
These scripts were removed from community.general in https://github.com/ansible-collections/community.general/pull/2696 and moved to ansible-community/contrib-scripts per https://github.com/ansible-community/community-topics/issues/16#issuecomment-853317111
(cherry picked from commit 97993eeb10)
* communication.rst: improve (#79751)
(cherry picked from commit 11a27eefa2)
* Fix broken docs links. (#79769)
(cherry picked from commit 5d71ace583)
Co-authored-by: Gineesh Madapparambath <net.gini@gmail.com>
Co-authored-by: Kristopher Henry Kram <kristopher@kristopherkram.com>
Co-authored-by: evangelionlion <546620084@qq.com>
Co-authored-by: Deric Crago <deric.crago@gmail.com>
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: Rune Juhl Jacobsen <rune@juhljacobsen.dk>
Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: antonc42 <antonc42@users.noreply.github.com>
Co-authored-by: Kenyon Ralph <kenyon@kenyonralph.com>
Co-authored-by: Matt Clay <matt@mystile.com>
* Add big support table (#79221)
Co-authored-by: samccann <samccann@redhat.com>
Co-authored-by: Matt Clay <matt@mystile.com>
(cherry picked from commit b3a1eabb7d)
* Add example of yaml file with --extra-vars (#79521)
(cherry picked from commit aa268b8db2)
* Fix `:ref:` usage in testing docs. (#79566)
(cherry picked from commit 245d516911)
* Typo in playbooks_blocks.rst (#79603)
(cherry picked from commit 69c874f478)
Co-authored-by: Matt Martz <matt@sivel.net>
Co-authored-by: Michael Mayer <mjmayer@ucdavis.edu>
Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Peter Tripp <petertripp@gmail.com>
* add ansible 7 porting guide to index page (#79254)
(cherry picked from commit 44f7ca4645)
* communication.rst: add Ansible MySQL WG information (#79269)
(cherry picked from commit 1c80209422)
* #59449: Removes translatable words from code blocks (#79193)
Co-authored-by: Jaroslav Klech <jklech@redhat.com>
(cherry picked from commit 65e725f08f)
* Add more documentation for InventoryData methods (#79288)
* Add more documentation for InventoryData methods
Reword some constructed documention and mention fetch_hostvars
* describe use cases for default strict behavior
Co-Authored-By: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
(cherry picked from commit a12a9b409f)
* blockinfile - document multiline marker behavior (#79292)
(cherry picked from commit f700047e69)
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: JaroslavKlech <klechh@gmail.com>
Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Matt Clay