Document / improve custom connector process

[Fizzadar]

Make example
List entry points for debugging
Enable loading via cli direct?

[goetzk]

I have the following documentation stub based on my experience, is it the sort of angle you'd like for this? If yes I can expand #1300 or put in a new PR for this change.

kgoetz@L23001:~/source/pyinfra$ git diff
diff --git a/docs/api/connectors.md b/docs/api/connectors.md
index eedb52dd..e849a0d6 100644
--- a/docs/api/connectors.md
+++ b/docs/api/connectors.md
@@ -136,6 +115,71 @@ class LocalConnector(BaseConnector):
         """
 
+## Where to make changes
+
+Connectors enable pyinfra to expand work done `in its 5 stages <deploy-process.html#how-pyinfra-works>`_ by providing methods which can be called at
+appropriate times.
+
+To hook in to to the various steps with the methods outlined below.
+```
+--> Loading config...
+--> Loading inventory...
+```
+`make_names_data` is used to supply inventory data about a host while at 'Loading inventory' stage.
+
+Its worth being aware up front that due to `make_names_data` being a `staticmethod` it has no automatic access to the parent classes attributes.
+To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
+(`getattr` and a function) are provided below.
+
+```py
+def load_settings():
+  settings = {}
+  # logic here
+  return settings
+
+class InventoryConnector(BaseConnector):
+  api_instance = external.ApiClient()
+  ...
+
+  @staticmethod
+  def make_names_data(_=None)
+    api_client = getattr(InventoryConnector, 'api_instance')
+    api_settings = load_settings()
+    ...
+```
+
+```
+--> Connecting to hosts...
+    [pytest.example.com] Connected
+```
+`connect` can be used to check access to a host is possible. If the connection fails `ConnectError` should be raised with a message to display on
+screen.
+
+```
+--> Preparing operations...
+--> Preparing Operations...
+    Loading: deploy_create_users.py
+    [pytest.example.com] Ready: deploy_create_users.py
+
+--> Detected changes:
+[list of changes here]
+
+--> Beginning operation run...
+--> Starting operation: sshd_install.py | Install OpenSSH server 
+    [pytest.example.com] No changes
+```
+
+`run_shell_command`, `put_file`, `get_file` and `rsync` can be used to change behaviour of pyinfra as it performs operations. 
+
+```
+--> Results:
+    Operation                                                                                            Hosts   Success   Error   No Change   
+--> Disconnecting from hosts...
+```
+
+`disconnect` can be used after all operations complete to clean up any connection/s remaining to the hosts being managed.
+
+
 ## pyproject.toml
 
 In order for pyinfra to gain knowledge about your connector, you need to add the following snippet to your connector's `pyproject.toml`:

[romain-dartigues]

I feel you, I still have not figured everything (I had not found @goetzk post).
I got my Incus/LXC working in #1368 if you want another example.