Feedback request: how can we make pyinfra’s documentation better

[Fizzadar]

I’d like to improve pyinfra’s documentation, I think there’s a few things that open come up and clearly need documenting better. Off the top of my head some of these are:

• operation execution (when do things execute)
• how to get output from an operation
• how to read system data before operations execute (ie the server.Command fact)

Would be amazing to hear what other things are unclear to people, and any ideas on how to better document or structure the docs would be much appreciated! 🙏

[goetzk]

Some docs related comments from me:

Developing and using inventory and execution connectors is not obvious to me ; i've started documentation for that at https://github.com/pyinfra-dev/pyinfra/compare/3.x...medeopolis:pyinfra:3.x-documentation-updates?expand=1 and will share it once i've confirmed its correct.

Outstanding questions which i haven't added to that doc (because i don't have the answers yet)

• if a inventory connector needs configuration (to access an API), how should the configuration be 'inserted'. environment? config file? to be confirmed...
• how to use pyinfra logger appropriately , eg logging at -v , -vv, -vvv (this might be obvious from the code but i haven't checked the code yet)
• how to package functions (connector, fact gathering, operations) for use with pyinfra (including recommended tools, configuration which needs to be created, paths to observe, etc)

Edit: on the subject of developing connectors:
There are lots of helpers/formatters available in pyinfra that are used during connector development. its possible to cargo cult most of the process but it would still be good to have more """python comments""" explaining what things do.