incomplete filter docs

Get Help
1

some doc pages on filters are incomplete.

Where’s the best place to start with discussing filter docs?

I was looking at filter docs today. This filter page looks great.

And somebody put a lot of work into a descriptive page to go with it.

These pages, not so much.

1 Like
2

I suspect it is because they are Jinja2 filters?

But I agree that better docs would be good, the Jinja2 docs are fairly minimal, I always appreciate lots of examples inAnsible docs.

3

lower and map are documented by Jinja, as they are part of that library. We do not document those in Ansible itself.

NEVERMIND: As per ipaddr, you can open an issue in the ansible.utils collection’s repo Issues · ansible-collections/ansible.utils · GitHub

That page you posted IS the proper documentation, also accessible (if the collection is installed) via ansible-doc -t filter ansible.utils.ipaddr

1 Like
4

Thanks for this.

Yes, at first I thought the jinja2 docs would be authoritative and so that’s cool.
But my brain also prefers better docs with examples.

Is this something a beginner like me can tackle?

I’m happy to learn how to contribute to these page myself, if I can figure out how to get started.

A bit more on my issue with ansible.builtin.map -

I find you’ve got to twiddle the Jinja2 way to get to the Ansible way. Template Designer Documentation — Jinja Documentation (3.1.x) contains Jinja2 speak. jinja-filters.map(*value: Iterable[Any]* , **args: Any* , ***kwargs: Any* ) → Iterable[Any] - sorry, what?

Also, there’s no CLI help - I was working offline yesterday, so the web was not an option. Doc command ansible-doc -t filter -l (and ansible-navigator doc -t filter -l) missed out the map filter.

vboxuser@fedoravm:~$ ansible-doc -t filter -l
...
ansible.builtin.log
ansible.builtin.mandatory  <----- where is ansible.builtin.map?
ansible.builtin.md5
ansible.builtin.normpath
...
5

Also, there’s no CLI help - I was working offline yesterday, so the web was not an option.

It was added in 2.19. The changelog includes ansible-doc - Return dynamic stub when reporting on Jinja filters and tests not explicitly documented in Ansible.

1 Like
6

It is my hope that we will make these stubs completely dynamic in a future release. As such, there would additionally be no functionality for adding per filter documentation for filters we don’t own.