Fine-tuning idem doc: A Power User's Guide

Have you ever felt like you're searching for a needle in a haystack when searching through documentation for a specific state? The "idem doc" subcommand is your best friend. Originally patterned after a similar capability in salt, this command is your inside scoop on any Idem state or function. Here's the nitty-gritty on its inception, capabilities, and some power-user tricks.

Purpose and Origins

You can use "idem doc" even if you don't have access to idemproject.io documentation. "idem doc" uses pop-tree under the hood to enumerate resources that were added to the hub -- so it is always up-to-date and accurate to the states available on your computer. idem doc was amped up during an innovation sprint for pyls-pop -- during that sprint we added line numbers and other details that made it so you could jump-to-references and use other handy IDE powers. You can also get json output from idem doc -- making it useful in automation for verifying the parameters available to a state and exposing parameters and their types/values to end users.

Leveraging JSON and jq

The most basic use case is to get the docs on a full reference:

idem doc exec.test.ping

output:

exec.test.ping:
    ----------
    doc:
        Immediately return success
    file:
        /home/akmod/PycharmProjects/idem-aws/venv/lib/python3.11/site-packages/idem/exec/test.py
    start_line_number:
        12
    end_line_number:
        17
    ref:
        exec.test.ping
    contracts:
        ----------
        pre:
        call:
            - exec.recursive_contracts.soft_fail.call
        post:
            - exec.recursive_contracts.init.post
    parameters:
        ----------
        hub:
            ----------

If you don't know the full reference to the function you need docs for, you can use a truncated version to list ALL the functions recursively under a ref. Since this output can be very long, we can use jq to shorten it to exactly what we want. Here is a command that lists all available present states on the hub and uses "--output=json" and jq to truncate the results to just the references:

idem doc states --output=json | jq -r '. | keys[] | select(. | endswith("present"))'

You could also narrow it down to just aws states.

idem doc states.aws --output=json | jq -r '. | keys[] | select(. | endswith("present"))'

You can also find all the "get" exec module functions available in idem-aws:

idem doc exec.aws --output=json | jq -r '. | keys[] | select(. | endswith("get"))'

Conclusion

"idem doc" has morphed from a humble guide to an essential swiss-army knife for developers. Whether you need to automate tasks or just better understand what you're working with, it's got you covered.