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

felixfontein · 2025-06-13T19:53:54Z

docs/docsite/rst/inventory_guide_iocage_basics.rst

+
+See: `Configuring a Shared IP Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-shared-ip-jail>`_
+
+* If iocage needs environment variable(s), use the option *env*. For example,


Since env is an option of the plugin, use :ansopt: to reference that option.

(https://docs.ansible.com/ansible/devel/dev_guide/style_guide/index.html#adding-links-to-module-and-plugin-options-and-return-values)

I hope I updated what you wanted.

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:

felixfontein · 2025-06-23T19:24:58Z

docs/docsite/rst/inventory_guide.rst

Please delete this file.

Sure. After the references are clear.

felixfontein · 2025-06-23T19:25:19Z

docs/docsite/rst/inventory_guide_iocage.rst

Please rename this file to iocage_inventory_guide.rst, and rename the other files accordingly.

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]>

vbotka · 2025-07-11T09:38:46Z

For the record: ... disallowed language 'sh' found.

vbotka · 2025-07-11T11:54:46Z

For the record:

An AttributeError error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: '/home/runner/work/community.general/community.general/.nox/docs-check/tmp/tmp7j736yzg/guide_iocage.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: rstcheck/rstcheck-core#3.
770
docs/docsite/rst/guide_iocage.rst:0:0: Unexpected error while parsing document: 'Values' object has no attribute 'env'

There are only two attribute env nobody complained before:

(env) > find docs/docsite/rst -name "iocage_inventory*" | xargs grep ':env'
docs/docsite/rst/iocage_inventory_guide_basics.rst:If iocage needs environment variable(s), use the option :ansopt:`community.general.iocage#inventory:env`. For example,
docs/docsite/rst/iocage_inventory_guide_dhcp.rst:Note: If the option :ansopt:`community.general.iocage#inventory:env` is used and :ansopt:`community.general.iocage#inventory:sudo` is enabled, enable also :ansopt:`community.general.iocage#inventory:sudo_preserve_env`. For example,

docs/docsite/rst/guide_iocage.rst

felixfontein · 2025-07-11T15:08:31Z

docs/docsite/rst/iocage_inventory_guide.rst

Can you rename this and the other iocage_inventory_guide_* files to guide_iocage_inventory_*?

No. You already asked me to rename them to iocage_inventory_guide_*

Sorry, I forgot about that. I think guide_iocage_inventory_* is better than the current name though; I'll create a PR once this is merged.

docs/docsite/rst/iocage_inventory_guide_basics.rst

docs/docsite/rst/iocage_inventory_guide_hooks.rst

felixfontein · 2025-07-11T15:12:36Z

For the record: ... disallowed language 'sh' found.

The error message should list the allowed languages. Use shell instead of sh.

docs/docsite/extra-docs.yml

docs/docsite/rst/iocage_inventory_guide_basics.rst

docs/docsite/rst/iocage_inventory_guide_dhcp.rst

docs/docsite/rst/iocage_inventory_guide_hooks.rst

docs/docsite/rst/iocage_inventory_guide_properties.rst

felixfontein · 2025-07-12T15:54:59Z

docs/docsite/rst/iocage_inventory_guide_tags.rst

+   PROPERTIES
+   ...
+   notes="any string"
+   Custom notes for miscellaneous tagging.
+   Default: none
+   Source: local


Shouldn't this be a code block (with language text)?

felixfontein · 2025-07-12T15:56:14Z

docs/docsite/rst/iocage_inventory_guide_tags.rst

+
+We will use the format `notes="tag1=value1 tag2=value2 ..."`.
+
+Note: The iocage tags has nothing to do with the :ref:`tags`


Suggested change

Note: The iocage tags has nothing to do with the :ref:`tags`

.. note::

The iocage tags have nothing to do with the :ref:`tags`.

felixfontein · 2025-07-12T15:57:00Z

docs/docsite/rst/iocage_inventory_guide_tags.rst

+:ansopt:`community.general.iocage#inventory:get_properties` must be enabled:
+
+.. code-block:: console
+
+   shell> cat hosts/02_iocage.yml


Suggested change

:ansopt:`community.general.iocage#inventory:get_properties` must be enabled:

.. code-block:: console

shell> cat hosts/02_iocage.yml

:ansopt:`community.general.iocage#inventory:get_properties` must be enabled.

For example, ``hosts/02_iocage.yml`` could look like:

felixfontein · 2025-07-12T15:57:18Z

docs/docsite/rst/iocage_inventory_guide_tags.rst

+Display tags and groups. Create a playbook:
+
+.. code-block:: console
+
+   shell> cat pb-test-groups.yml


Suggested change

Display tags and groups. Create a playbook:

.. code-block:: console

shell> cat pb-test-groups.yml

Display tags and groups. Create a playbook ``pb-test-groups.yml``:

Co-authored-by: Felix Fontein <[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 added 2 commits July 11, 2025 08:10

Added docs Inventory Guide.

f3c1697

Errata docs Inventory Guide.

3d853fb

vbotka and others added 6 commits July 11, 2025 08:10

Update docs/docsite/rst/inventory_guide_iocage_basics.rst

6c2d00e

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

Indent the note block.

bdd5af9

Update docs/docsite/rst/inventory_guide_iocage_hooks.rst

a945302

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

Update docs/docsite/rst/inventory_guide_iocage_dhcp.rst

7e59f8b

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

Update docs/docsite/rst/inventory_guide_iocage_hooks.rst

8f95425

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

Fix ansval.

1c91a91

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 added 2 commits July 11, 2025 11:30

Add guide_iocage.rst and inventory_guide_iocage*.rst

6ec251f

Fix 'disallowed language sh found'.

360d9f7

Remove note block.

9a947c0

felixfontein reviewed Jul 11, 2025

View reviewed changes

Remove include which triggers a bug in rstcheck.

3c014fe

felixfontein reviewed Jul 12, 2025

View reviewed changes

felixfontein mentioned this pull request Jul 12, 2025

Extra docs linting: ensure that documents referenced in extra-docs.yml are actually there ansible-community/antsibull-docs#398

Open

ansibullbot added the has_issue label Jul 12, 2025

vbotka and others added 4 commits July 12, 2025 18:54

Update docs/docsite/extra-docs.yml

5061a3c

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

Update docs/docsite/rst/iocage_inventory_guide_basics.rst

dde36f9

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

Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst

9fe0d28

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

Update docs/docsite/rst/iocage_inventory_guide_dhcp.rst

d8cb1ba

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

ansibullbot added needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI and removed needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI labels Jul 12, 2025

Update docs/docsite/rst/iocage_inventory_guide_hooks.rst

efdfa10

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

ansibullbot added needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR labels Jul 12, 2025

Update docs/docsite/rst/iocage_inventory_guide_properties.rst

b880ee7

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

ansibullbot removed the needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI label Jul 12, 2025


		See: `Configuring a Shared IP Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-shared-ip-jail>`_

		* If iocage needs environment variable(s), use the option env. For example,


		We will use the format `notes="tag1=value1 tag2=value2 ..."`.

		Note: The iocage tags has nothing to do with the :ref:`tags`

-Note: The iocage tags has nothing to do with the :ref:`tags`
+.. note::
+    The iocage tags have nothing to do with the :ref:`tags`.

Added docs Inventory Guide. #10239

Are you sure you want to change the base?

Added docs Inventory Guide. #10239

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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

vbotka commented Jul 11, 2025 •

edited

Loading

vbotka commented Jul 11, 2025 •

edited

Loading

vbotka Jul 11, 2025 •

edited

Loading