Added docs Inventory Guide. #10239

vbotka · 2025-06-13T05:54:45Z

SUMMARY

Add Inventory (Plugin) Guide

Guides
* community.general Filter Guide
* community.general Inventory (Plugin) Guide
* community.general Test (Plugin) Guide

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

NA

ADDITIONAL INFORMATION

NA

felixfontein

Thanks for your contribution! I've added some first comments below.

docs/docsite/extra-docs.yml

docs/docsite/rst/inventory_guide_iocage.rst

docs/docsite/rst/inventory_guide_iocage_aliases.rst

docs/docsite/rst/inventory_guide_iocage_basics.rst

russoz · 2025-06-15T00:55:59Z

I think @felixfontein 's line of thought makes sense, these guides should be put together as iocage guides, instead of using major categories for the types of the plugins. I am not going through the contents of the texts today, but I trust Felix's sharp eyes must have caught all (or most) of necessary adjustments. And if we pick something else later on we can always adjust later on.

felixfontein · 2025-06-15T07:21:00Z

I haven't checked all files in detail yet, I mainly skimmed over it and added comments for some things that seemed to happen more than once / I noticed on the first pass. I'll take a closer look later :)

russoz · 2025-06-15T09:58:07Z

Okie, I'll do the same - but not today

russoz

couple of comments

docs/docsite/rst/inventory_guide_iocage_dhcp.rst

docs/docsite/rst/inventory_guide_iocage_hooks.rst

docs/docsite/extra-docs.yml

russoz · 2025-06-19T06:00:26Z

docs/docsite/rst/inventory_guide_iocage_hooks.rst

+.. code-block:: bash
+
+   shell> cat /zroot/iocage/jails/srv_1/root/etc/dhclient-exit-hooks
+   case "$reason" in
+       "BOUND"|"REBIND"|"REBOOT"|"RENEW")
+       echo $new_ip_address > /var/db/dhclient-hook.address.$interface
+       ;;
+   esac


In other .rst files, to showcase the contents of yaml files, you created two code-blocks, one "console" with the cat command and the other one with the content. Here it is all in one block. I believe both ways to be OK, but whichever one you want to use, apply it consistently to all cases.

I consistently apply whatever works. The single bash block works fine here. This is not the case with yaml.

This is definitely not a generic "Inventory Guide" but rather an "iocage inventory guide". I think it should be named accordingly. Maybe a new section should be opened, like "Technology Guide" or something similar - I don't think it fits well in any of the existing sections.

I've already told you:

This is up to you. I'm only interested in the "inventory iocage" guide. Feel free to place it wherever you'd like.

I consistently apply whatever works. The single bash block works fine here. This is not the case with yaml.

But the two cases are actually just one case, which is showing content of a file with cat. I reckon they should be formatted the same way. IMHO the current disposition is not a good editorial choice.

This is definitely not a generic "Inventory Guide" but rather an "iocage inventory guide". I think it should be named accordingly. Maybe a new section should be opened, like "Technology Guide" or something similar - I don't think it fits well in any of the existing sections.

I've already told you:

This is up to you. I'm only interested in the "inventory iocage" guide. Feel free to place it wherever you'd like.

And as I wrote in that comment, the suggested placement is a bit off. That being said, the second half of that comment was intended to be an invitation to a discussion, to you, to @felixfontein and anyone else in the community who might want to chip in.

I changed problematic pygments to console. I won't use ansible-output because the playbook outputs are YAML. Thank you.

BTW, the ansible-output lexer is in https://github.com/ansible-community/ansible-pygments/blob/main/src/ansible_pygments/lexers.py#L44-L214. If someone wants to create a lexer for Ansible output with YAML, that's the place where it belongs to. Not sure how hard that would be though, since handling mixing YAML, regular Ansible output, and diff output isn't trivial...

... the second half of that comment was intended to be an invitation to a discussion

I created this PR. I don't need an invitation.

I did that out of politeness to you and to others, not out of your necessity.

That being said, please create a new section for your guide - I suggested "Technology Guide" but you may prefer something else. Just keep in mind, as mentioned before, that "Inventory Guide" is misleading because this is not about inventories in general, but rather about one single technology that happens to provide an inventory.

And please mark the command line as console and the output as bash for consistency.

... create a lexer for Ansible output with YAML

JSON is a subset of YAML.

Yeah, but not the other way around :) The advantage of a JSON object or list is that it's clear when it's done (assuming it doesn't have syntax errors). For YAML that's definitely not the case, which makes an Ansible output parser for YAML output harder than for JSON output.

russoz

Additional comments and responses.

docs/docsite/rst/inventory_guide_iocage_hooks.rst

docs/docsite/rst/inventory_guide_iocage_properties.rst

docs/docsite/rst/inventory_guide_iocage_hooks.rst

docs/docsite/rst/inventory_guide_iocage_dhcp.rst

russoz · 2025-06-23T05:33:16Z

docs/docsite/rst/inventory_guide_iocage_hooks.rst

+.. code-block:: bash
+
+   shell> cat /zroot/iocage/jails/srv_1/root/etc/dhclient-exit-hooks
+   case "$reason" in
+       "BOUND"|"REBIND"|"REBOOT"|"RENEW")
+       echo $new_ip_address > /var/db/dhclient-hook.address.$interface
+       ;;
+   esac


... the second half of that comment was intended to be an invitation to a discussion

I created this PR. I don't need an invitation.

I did that out of politeness to you and to others, not out of your necessity.

That being said, please create a new section for your guide - I suggested "Technology Guide" but you may prefer something else. Just keep in mind, as mentioned before, that "Inventory Guide" is misleading because this is not about inventories in general, but rather about one single technology that happens to provide an inventory.

And please mark the command line as console and the output as bash for consistency.

vbotka · 2025-06-23T06:57:45Z

... mark the command line as console and the output as bash

I changed the pygment to sh. Quoting man dhclient-script:

... check for the existence of /etc/dhclient-exit-hooks. If found, it
will be sourced (see sh(1))

vbotka · 2025-06-23T09:12:34Z

For the record:

The file inventory_guide.rst serves the purpose of inventory_guide_iocage.rst temporary integration. Please remove the BOTMETA entry after you decide where to place it

docs/docsite/rst/inventory_guide.rst: {}

felixfontein

I didn't go through everything, but here's a bunch of more comments:

docs/docsite/rst/inventory_guide.rst

docs/docsite/rst/inventory_guide_iocage.rst

docs/docsite/rst/inventory_guide_iocage_basics.rst

docs/docsite/rst/inventory_guide_iocage_dhcp.rst

docs/docsite/rst/inventory_guide_iocage_hooks.rst

vbotka · 2025-06-23T22:09:10Z

For the record:

docs/docsite/rst/inventory_guide_iocage_aliases.rst:117:0: (ERROR/3) Unknown interpreted text role "ansvalue".

felixfontein · 2025-06-24T04:25:59Z

Yep, sorry, it's :ansval:, not :ansvalue:...

Co-authored-by: Felix Fontein <[email protected]>

patchback · 2025-07-12T18:43:10Z

Backport to stable-11: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-11/563b29e12ab774814ff5171a454f3ef5948e99c8/pr-10239

Backported as #10395

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

felixfontein · 2025-07-12T18:43:17Z

@vbotka thanks for your contribution!
@russoz thanks for reviewing!

* Added docs Inventory Guide. * Errata docs Inventory Guide. * Fix docs Inventory Guide error: use ASCII quotes. * Fix docs Inventory Guide various lint errors. * Added docs Inventory Guide BOTMETA entries. * Fix docs Inventory Guide lint errors: trailing whitespace * Fix docs Inventory Guide lint errors: force yaml pygment * Fix docs Inventory Guide lint errors: No way to force yaml pygment in code-block * Update docs/docsite/rst/inventory_guide_iocage.rst Co-authored-by: Felix Fontein <[email protected]> * Update docs/docsite/rst/inventory_guide_iocage_aliases.rst Thank you for the explanation! Co-authored-by: Felix Fontein <[email protected]> * Update docs/docsite/rst/inventory_guide_iocage_aliases.rst Co-authored-by: Felix Fontein <[email protected]> * Updated docs Inventory Guide. * Problematic pygments changed to 'console'. * Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Update docs/docsite/rst/inventory_guide_iocage_properties.rst Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Co-authored-by: Alexei Znamensky <[email protected]> * Put dhclient-exit-hooks into the sh code-block. * Fix the code-block. * Update docs/docsite/rst/inventory_guide_iocage.rst Update docs/docsite/rst/inventory_guide_iocage_aliases.rst Update docs/docsite/rst/inventory_guide_iocage_basics.rst Co-authored-by: Felix Fontein <[email protected]> * Remove tabs. * Update docs/docsite/rst/inventory_guide_iocage_basics.rst Co-authored-by: Felix Fontein <[email protected]> * Indent the note block. * Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Update docs/docsite/rst/inventory_guide_iocage_dhcp.rst Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Co-authored-by: Felix Fontein <[email protected]> * Fix ansval. * Add guide_iocage.rst and inventory_guide_iocage*.rst * Fix 'disallowed language sh found'. * Remove note block. * Remove include which triggers a bug in rstcheck. * Update docs/docsite/extra-docs.yml Update docs/docsite/rst/iocage_inventory_guide_basics.rst Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst Update docs/docsite/rst/iocage_inventory_guide_hooks.rst Update docs/docsite/rst/iocage_inventory_guide_properties.rst Update docs/docsite/rst/iocage_inventory_guide_tags.rst Update docs/docsite/rst/iocage_inventory_guide_hooks.rst Update docs/docsite/rst/iocage_inventory_guide_properties.rst Co-authored-by: Felix Fontein <[email protected]> * Put man iocage quotation into the text code block. --------- Co-authored-by: Felix Fontein <[email protected]> Co-authored-by: Alexei Znamensky <[email protected]> (cherry picked from commit 563b29e)

…10395) Added docs Inventory Guide. (#10239) * Added docs Inventory Guide. * Errata docs Inventory Guide. * Fix docs Inventory Guide error: use ASCII quotes. * Fix docs Inventory Guide various lint errors. * Added docs Inventory Guide BOTMETA entries. * Fix docs Inventory Guide lint errors: trailing whitespace * Fix docs Inventory Guide lint errors: force yaml pygment * Fix docs Inventory Guide lint errors: No way to force yaml pygment in code-block * Update docs/docsite/rst/inventory_guide_iocage.rst * Update docs/docsite/rst/inventory_guide_iocage_aliases.rst Thank you for the explanation! * Update docs/docsite/rst/inventory_guide_iocage_aliases.rst * Updated docs Inventory Guide. * Problematic pygments changed to 'console'. * Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Update docs/docsite/rst/inventory_guide_iocage_properties.rst Update docs/docsite/rst/inventory_guide_iocage_hooks.rst * Put dhclient-exit-hooks into the sh code-block. * Fix the code-block. * Update docs/docsite/rst/inventory_guide_iocage.rst Update docs/docsite/rst/inventory_guide_iocage_aliases.rst Update docs/docsite/rst/inventory_guide_iocage_basics.rst * Remove tabs. * Update docs/docsite/rst/inventory_guide_iocage_basics.rst * Indent the note block. * Update docs/docsite/rst/inventory_guide_iocage_hooks.rst Update docs/docsite/rst/inventory_guide_iocage_dhcp.rst Update docs/docsite/rst/inventory_guide_iocage_hooks.rst * Fix ansval. * Add guide_iocage.rst and inventory_guide_iocage*.rst * Fix 'disallowed language sh found'. * Remove note block. * Remove include which triggers a bug in rstcheck. * Update docs/docsite/extra-docs.yml Update docs/docsite/rst/iocage_inventory_guide_basics.rst Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst Update docs/docsite/rst/iocage_inventory_guide_hooks.rst Update docs/docsite/rst/iocage_inventory_guide_properties.rst Update docs/docsite/rst/iocage_inventory_guide_tags.rst Update docs/docsite/rst/iocage_inventory_guide_hooks.rst Update docs/docsite/rst/iocage_inventory_guide_properties.rst * Put man iocage quotation into the text code block. --------- (cherry picked from commit 563b29e) Co-authored-by: Vladimir Botka <[email protected]> Co-authored-by: Felix Fontein <[email protected]> Co-authored-by: Alexei Znamensky <[email protected]>

ansibullbot added docs docs_only labels Jun 13, 2025

This comment was marked as outdated.

Sign in to view

ansibullbot added ci_verified Push fixes to PR branch to re-run CI needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR labels Jun 13, 2025

felixfontein added the check-before-release PR will be looked at again shortly before release and merged if possible. label Jun 13, 2025

ansibullbot removed ci_verified Push fixes to PR branch to re-run CI needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR docs_only labels Jun 13, 2025

felixfontein reviewed Jun 13, 2025

View reviewed changes

felixfontein added the backport-11 Automatically create a backport for the stable-10 branch label Jun 16, 2025

russoz reviewed Jun 19, 2025

View reviewed changes

ansibullbot added stale_ci CI is older than 7 days, rerun before merging and removed stale_ci CI is older than 7 days, rerun before merging labels Jun 22, 2025

russoz reviewed Jun 23, 2025

View reviewed changes

felixfontein reviewed Jun 23, 2025

View reviewed changes

ansibullbot added the stale_ci CI is older than 7 days, rerun before merging label Jul 2, 2025

vbotka force-pushed the docs-guide-inventory branch from a6e0c00 to 1c91a91 Compare July 11, 2025 06:11

ansibullbot removed the stale_ci CI is older than 7 days, rerun before merging label Jul 11, 2025

vbotka and others added 17 commits July 12, 2025 20:24

Fix ansval.

8cc7e7a

Add guide_iocage.rst and inventory_guide_iocage*.rst

4c4c78c

Fix 'disallowed language sh found'.

788f776

Remove note block.

7f49c9b

Remove include which triggers a bug in rstcheck.

948564d

Update docs/docsite/extra-docs.yml

86115d2

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_basics.rst

50ee677

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst

8446913

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst

1e6e438

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_hooks.rst

dc3646d

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_properties.rst

9c28dce

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_tags.rst

ea76946

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_tags.rst

b464933

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_tags.rst

9d64cf7

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_hooks.rst

387b864

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_hooks.rst

1c94a41

Co-authored-by: Felix Fontein <[email protected]>

Update docs/docsite/rst/iocage_inventory_guide_properties.rst

63bcde7

Co-authored-by: Felix Fontein <[email protected]>

vbotka force-pushed the docs-guide-inventory branch from 3b7c5d2 to 63bcde7 Compare July 12, 2025 18:25

Put man iocage quotation into the text code block.

897740f

felixfontein approved these changes Jul 12, 2025

View reviewed changes

felixfontein merged commit 563b29e into ansible-collections:main Jul 12, 2025
122 checks passed

patchback bot mentioned this pull request Jul 12, 2025

[PR #10239/563b29e1 backport][stable-11] Added docs Inventory Guide. #10395

Merged

felixfontein mentioned this pull request Jul 12, 2025

iocage inventory guide: adjust filenames, fix typo #10396

Merged

vbotka deleted the docs-guide-inventory branch July 12, 2025 22:41

felixfontein removed the check-before-release PR will be looked at again shortly before release and merged if possible. label Jul 13, 2025

patchback bot mentioned this pull request Jul 13, 2025

[PR #10396/3787808e backport][stable-11] iocage inventory guide: adjust filenames, fix typo #10403

Merged

Added docs Inventory Guide. #10239

Added docs Inventory Guide. #10239

Uh oh!

Conversation

vbotka commented Jun 13, 2025

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

Uh oh!

This comment was marked as outdated.

felixfontein left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

russoz commented Jun 15, 2025

Uh oh!

felixfontein commented Jun 15, 2025

Uh oh!

russoz commented Jun 15, 2025

Uh oh!

russoz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

russoz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vbotka commented Jun 23, 2025

Uh oh!

vbotka commented Jun 23, 2025

Uh oh!

felixfontein left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

patchback bot commented Jul 12, 2025 •

edited

Loading