x*: adjust docs #9308

russoz · 2024-12-22T06:40:52Z

SUMMARY

Adjust documentation blocks.

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

plugins/modules/xattr.py
plugins/modules/xbps.py
plugins/modules/xcc_redfish_command.py
plugins/modules/xenserver_facts.py
plugins/modules/xenserver_guest.py
plugins/modules/xenserver_guest_info.py
plugins/modules/xenserver_guest_powerstate.py
plugins/modules/xfconf.py
plugins/modules/xfconf_info.py
plugins/modules/xfs_quota.py
plugins/modules/xml.py

ansibullbot · 2024-12-22T06:43:55Z

cc @bcoca @bushvin @bvitnik @caphrim007 @cheese @cmprescott @dagwieers @dinoocch @jbenden @panyy3 @renxulei @sm4rk0 @tbielawa @the-maldridge
click here for bot help

plugins/modules/xattr.py

plugins/modules/xml.py

bvitnik · 2024-12-22T13:31:20Z

Hi. Is there a discussion regarding these changes? I'd just like to understand the background.

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

russoz · 2024-12-22T19:19:41Z

Hi @bvitnik , there has been no prior discussion, but the main motivation behind this initiative is the fact that the documentation blocks (including EXAMPLES and RETURN) have inconsistencies across the modules, and no mechanism to fix them.

The main issues (but not limited to) in the YAML docs are:

inconsistent indentation within the YAML doc, and between different modules
capitalisation and punctuation of descriptions and notes
use of markup

As a maintainer of the collection I have been building this tool andebox (published in PyPI) primarily to help running tests, but then a feature of generating the docsite to check how those docs are rendered was added, and the latest addition is exactly one that goes through the module, extract the YAML blocks, manipulates them and write them back.

The library ruamel.yaml is being used to manipulate the YAML content. The result is far from perfect, I have to verify and oft times adjust them, but it beats doing that manually for every single module.

If you (or any maintainer of modules) are not happy with the reformatting, I will gladly roll it back, though perhaps keeping some of the corrections in markup, capitalisation and punctuation.

Hope that clarifies what's going on.

russoz · 2024-12-23T01:41:51Z

plugins/modules/xenserver_guest.py

+      - 'Example:'
+      - '  folder: /folder1/folder2'


@bvitnik I think this would be better suited for the EXAMPLES block below, but I am not too familiar with xenserver to be sure of where/how to place it.

I think it's better to leave it here. It would be hard to spot in the EXAMPLES block. The idea here is to emphasize the format of the value. Not many people know that folders can have arbitrarily deep hierarchy.

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

russoz · 2024-12-23T02:26:58Z

plugins/modules/xenserver_guest_info.py

+  - Minimal supported version of XenServer is 5.6.
+  - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
+  - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
+    Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible
+    Control Node to use it. Latest version of the library can also be acquired from GitHub:
+    U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)'
+  - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you
+    are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
+  - 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=no) which
+    requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
 requirements:
- XenAPI
+  - XenAPI


@bvitnik also, this block is repeated in all but one of the modules. I would suggest transofrming it into a doc fragment, to make it DRY.

This is a good idea now that I look at it. My initial idea was probably to keep notes specific to the module because there was a plan to implement a slew of other modules that never came into being. Each module was expected to have slightly different notes. Also, the three modules mentioned here were originally a single module and were split into three at later time (copy-paste job). Since there are some updates to be made on the notes anyway, I will consider moving them to doc fragment.

felixfontein · 2024-12-23T10:03:20Z

Looks good from my side. @bvitnik do you want to take a closer look as well?

bvitnik · 2024-12-23T12:14:14Z

@russoz Hi. Sorry for the late response. Thanks for sharing the background, much appreciated. While I don't like the proposed indentation style, if it is for a greater good (global consistency), I will not complain :). You are good to go.

@felixfontein, we are good to go.

patchback · 2024-12-23T17:58:06Z

Backport to stable-9: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply f9bfe4e on top of patchback/backports/stable-9/f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6/pr-9308

Backporting merged PR #9308 into main

Ensure you have a local repo clone of your fork. Unless you cloned it
from the upstream, this would be your origin remote.
Make sure you have an upstream repo added as a remote too. In these
instructions you'll refer to it by the name upstream. If you don't
have it, here's how you can add it:
```
$ git remote add upstream https://github.com/ansible-collections/community.general.git
```

Ensure you have the latest copy of upstream and prepare a branch
that will hold the backported code:

$ git fetch upstream
$ git checkout -b patchback/backports/stable-9/f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6/pr-9308 upstream/stable-9

Now, cherry-pick PR x*: adjust docs #9308 contents into that branch:
```
$ git cherry-pick -x f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6
```
If it'll yell at you with something like fatal: Commit f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6 is a merge but no -m option was given., add -m 1 as follows instead:
```
$ git cherry-pick -m1 -x f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6
```
At this point, you'll probably encounter some merge conflicts. You must
resolve them in to preserve the patch from PR x*: adjust docs #9308 as close to the
original as possible.

Push this branch to your fork on GitHub:

$ git push origin patchback/backports/stable-9/f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6/pr-9308

Create a PR, ensure that the CI is green. If it's not — update it so that
the tests and any other checks pass. This is it!
Now relax and wait for the maintainers to process your pull request
when they have some cycles to do reviews. Don't worry — they'll tell you if
any improvements are necessary when the time comes!

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

patchback · 2024-12-23T17:58:12Z

Backport to stable-10: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-10/f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6/pr-9308

Backported as #9342

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

felixfontein · 2024-12-23T17:58:18Z

@russoz thanks for working on this!
@bvitnik thanks for reviewing! :)

* adjust docs * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> * fix capitalisation * add markup to references of the xe command (xenserver) * add missing markup * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]> (cherry picked from commit f9bfe4e)

x*: adjust docs (#9308) * adjust docs * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> * fix capitalisation * add markup to references of the xe command (xenserver) * add missing markup * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]> (cherry picked from commit f9bfe4e) Co-authored-by: Alexei Znamensky <[email protected]>

adjust docs

74dca5c

ansibullbot added docs module module plugins plugin (any type) labels Dec 22, 2024

felixfontein added check-before-release PR will be looked at again shortly before release and merged if possible. backport-9 Automatically create a backport for the stable-9 branch backport-10 Automatically create a backport for the stable-10 branch labels Dec 22, 2024

felixfontein reviewed Dec 22, 2024

View reviewed changes

plugins/modules/xattr.py Show resolved Hide resolved

plugins/modules/xml.py Outdated Show resolved Hide resolved

plugins/modules/xml.py Outdated Show resolved Hide resolved

Update plugins/modules/xml.py

4aa00d8

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

ansibullbot added the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR label Dec 22, 2024

russoz mentioned this pull request Dec 23, 2024

xattr: read, all, and keys sound like "states" we should deprecate once we have a replacement #9317

Open

1 task

russoz changed the title ~~adjust docs~~ x*: adjust docs Dec 23, 2024

ansibullbot added the has_issue label Dec 23, 2024

fix capitalisation

fb5cf7e

ansibullbot removed the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR label Dec 23, 2024

russoz commented Dec 23, 2024

View reviewed changes

russoz and others added 3 commits December 23, 2024 14:45

add markup to references of the xe command (xenserver)

4a9e838

add missing markup

990f77f

Update plugins/modules/xml.py

97e9e2a

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

russoz commented Dec 23, 2024

View reviewed changes

felixfontein removed the check-before-release PR will be looked at again shortly before release and merged if possible. label Dec 23, 2024

felixfontein merged commit f9bfe4e into ansible-collections:main Dec 23, 2024
129 checks passed

patchback bot mentioned this pull request Dec 23, 2024

[PR #9308/f9bfe4e4 backport][stable-10] x*: adjust docs #9342

Merged

russoz deleted the xmods-docs branch December 23, 2024 19:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

x*: adjust docs #9308

x*: adjust docs #9308

russoz commented Dec 22, 2024

ansibullbot commented Dec 22, 2024

bvitnik commented Dec 22, 2024

russoz commented Dec 22, 2024 •

edited

Loading

russoz Dec 23, 2024

bvitnik Dec 23, 2024

russoz Dec 23, 2024

bvitnik Dec 23, 2024 •

edited

Loading

felixfontein commented Dec 23, 2024

bvitnik commented Dec 23, 2024

patchback bot commented Dec 23, 2024 •

edited

Loading

patchback bot commented Dec 23, 2024 •

edited

Loading

felixfontein commented Dec 23, 2024

x*: adjust docs #9308

x*: adjust docs #9308

Conversation

russoz commented Dec 22, 2024

SUMMARY

ISSUE TYPE

COMPONENT NAME

ansibullbot commented Dec 22, 2024

bvitnik commented Dec 22, 2024

russoz commented Dec 22, 2024 • edited Loading

russoz Dec 23, 2024

Choose a reason for hiding this comment

bvitnik Dec 23, 2024

Choose a reason for hiding this comment

russoz Dec 23, 2024

Choose a reason for hiding this comment

bvitnik Dec 23, 2024 • edited Loading

Choose a reason for hiding this comment

felixfontein commented Dec 23, 2024

bvitnik commented Dec 23, 2024

patchback bot commented Dec 23, 2024 • edited Loading

Backport to stable-9: 💔 cherry-picking failed — conflicts found

Backporting merged PR #9308 into main

patchback bot commented Dec 23, 2024 • edited Loading

Backport to stable-10: 💚 backport PR created

felixfontein commented Dec 23, 2024

russoz commented Dec 22, 2024 •

edited

Loading

bvitnik Dec 23, 2024 •

edited

Loading

patchback bot commented Dec 23, 2024 •

edited

Loading

patchback bot commented Dec 23, 2024 •

edited

Loading