Add docs for vault_login_token filter

[briantist]

SUMMARY

Resolves #260

Also updates the committed docs build stuff (the output of antsibull-docs sphinx-init). this was moved to #306

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

vault_login_token

[github-actions]

Docs Build 📝

Thank you for contribution!✨

This PR has been merged and the docs are now incorporated into main:
https://ansible-collections.github.io/community.hashi_vault/branch/main

[briantist]

The changes needed in core are in devel but not in stable-2.13. Landing the YAML docs alone should not break anything, but trying to add references to the page that would be generated will be broken in earlier versions, so I will need to either:

• wait for the core support to land in 2.13 before doing any of this
• add the filter doc page, but do not make any references to it, and land that now, then add references later

[codecov]

Codecov Report

Merging #263 (8b8b54b) into main (ba83998) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #263   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          73       73           
  Lines        3679     3679           
  Branches      313      313           
=======================================
  Hits         3630     3630           
  Misses         40       40           
  Partials        9        9           

Flag	Coverage Δ
env_docker-default	98.66% <ø> (ø)
integration	81.02% <ø> (ø)
sanity	38.88% <ø> (ø)
target_ansible-doc	100.00% <ø> (ø)
target_auth_approle	89.47% <ø> (ø)
target_auth_aws_iam	50.00% <ø> (ø)
target_auth_azure	53.84% <ø> (ø)
target_auth_cert	86.36% <ø> (ø)
target_auth_jwt	91.30% <ø> (ø)
target_auth_ldap	89.47% <ø> (ø)
target_auth_none	100.00% <ø> (ø)
target_auth_token	73.07% <ø> (ø)
target_auth_userpass	85.71% <ø> (ø)
target_connection_options	74.76% <ø> (ø)
target_controller	83.25% <ø> (ø)
target_filter_vault_login_token	77.77% <ø> (ø)
target_import	38.88% <ø> (ø)
target_lookup_hashi_vault	81.33% <ø> (ø)
target_lookup_vault_ansible_settings	55.87% <ø> (ø)
target_lookup_vault_kv1_get	91.30% <ø> (ø)
target_lookup_vault_kv2_get	91.66% <ø> (ø)
target_lookup_vault_login	88.57% <ø> (ø)
target_lookup_vault_read	90.00% <ø> (ø)
target_lookup_vault_token_create	79.24% <ø> (ø)
target_lookup_vault_write	57.57% <ø> (ø)
target_module_utils	97.02% <ø> (ø)
target_module_vault_kv1_get	87.50% <ø> (ø)
target_module_vault_kv2_get	87.23% <ø> (ø)
target_module_vault_login	83.72% <ø> (ø)
target_module_vault_pki_generate_certificate	78.72% <ø> (ø)
target_module_vault_read	85.71% <ø> (ø)
target_module_vault_token_create	91.66% <ø> (ø)
target_module_vault_write	56.46% <ø> (ø)
target_modules	78.61% <ø> (ø)
units	96.24% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
plugins/lookup/vault_login.py	100.00% <ø> (ø)
plugins/lookup/vault_token_create.py	100.00% <ø> (ø)
plugins/modules/vault_login.py	100.00% <ø> (ø)
plugins/modules/vault_token_create.py	100.00% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[briantist]

I'm going to hold off on this for now, possibly until version 4.0.0 / ansible-core 2.14, since the feature will not be available until then.

I could add just the sidecar docs for now without linking to them with references (because that breaks if docs are rendered with an ansible version earlier than devel, since the target ref won't exist). But if I do that, I am not testing them in my collection.

To remedy that, I could choose to use devel with the docs build, and maybe I will, but if I use devel, I am not certain then if I could be allowing things in (like the aforementioned references) which would break other docs builds.

If the latest (as opposed to devel) docs on docs.ansible.com are rendered with the latest stable version of ansible-core for example, I'd be introducing broken references that way.

[acozine]

This is great information to have in the docs, and great functionality to have in Ansible! Thanks @briantist.

I've made a few wording suggestions. My interpretation of what the filter does may not be correct, but I hope the suggestions will help clarify the docs a bit.

[briantist]

@acozine thanks I will have to look over your suggestions in more detail later, but I think what's there will make more sense if you look at the existing filter guide (which is where I pulled these description) where I've gone into more detail: https://ansible-collections.github.io/community.hashi_vault/pr/263/collections/community/hashi_vault/docsite/filter_guide.html

The challenge is writing something for a documentation page where I can't include all of that context.

[briantist]

Current failure is not related to this PR as far as I can tell:

• Docs builds are failing with Sphinx 5.2.0.post0 ansible-community/antsibull-docs#39

[russoz]

not very familiar with the doc generation machinery, but as far as I can tell, LGTM

[briantist]

@felixfontein @russoz thanks for reviewing this!