From 09a9ac86ffb7a92b94380b5f2a1525bf523ac245 Mon Sep 17 00:00:00 2001
From: Karl Goetz <karl@medeopolis.au>
Date: Thu, 13 Feb 2025 11:44:40 +1100
Subject: [PATCH 1/2] Add documentation on extending

its bare bones, but means I've written _something_
---
 docs/extending.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 docs/extending.rst

diff --git a/docs/extending.rst b/docs/extending.rst
new file mode 100644
index 000000000..19bc4893c
--- /dev/null
+++ b/docs/extending.rst
@@ -0,0 +1,140 @@
+Extending Pyinfra
+=================
+
+Every site needs an integration or fact whichs unique to them. The pages below here describe the process of building a pip installable pyinfra package
+with one or more custom facts, connectors, or operations.
+
+Packaging for Pyinfra extensions
+--------------------------------
+
+Create venv
+
+::
+
+  virtualenv ~/.venvs/pyinfra_hacking
+
+Install dependencies
+
+::
+
+  source ~/.venvs/pyinfra_hacking/bin/activate
+  pip install build setuptools
+
+Create development environment
+
+::
+
+  mkdir -p ~/pyinfra_extension/pyinfra_extension/
+  cd ~/pyinfra_extension
+  echo 'pyinfra' > requirements.txt
+  echo 'pyinfra_*egg-info' >> .gitignore
+  echo 'dist/' >> .gitignore
+  touch pyinfra_extension/__init__.py
+  git init .
+  git add .
+  git commit -avm 'environment prepared'
+
+Add a ``pyproject.toml`` file, its contents should look something like the following:
+
+::
+
+  [build-system]
+  requires = ["setuptools"]
+  build-backend = "setuptools.build_meta"
+
+  [project]
+  name = "pyinfra_extension"
+  version = "0.0.1"
+  dependencies = [
+      "pyinfra",
+  ]
+
+If creating a custom Inventory/Execution connector, add the following too:
+
+::
+
+  [project.entry-points.'pyinfra.connectors']
+  # Key = Entry point name
+  # Value = module_path:class_name
+  extendor = 'pyinfra_extension.connectors:ExtendedConnector'
+
+
+Build it!
+
+::
+
+  python -m build
+
+Install it! This will create an editable install so your module will load in pyinfra but still be editable in this repository.
+
+::
+
+  pip install --editable .
+
+
+And with that the extension is ready to go!
+
+Files for your extension should be in ``pyinfra_extension``, eg:
+
+::
+
+  ~/pyinfra_extension$ ls -1 pyinfra_extension/
+  connectors.py
+  facts.py
+  __init__.py
+  operations.py
+  other_relevant_file.py
+
+And the connector you registered in ``pyproject.toml`` needs to match the path to, and class name in, ``connectors.py``:
+
+::
+
+  ~/pyinfra_extension$ grep ExtendedConnector pyinfra_extension/connectors.py
+  class ExtendedConnector(BaseConnector):
+
+
+Custom libraries
+----------------
+
+If additional libraries are needed in a custom plugin they should be included with it and imported by connectors/facts/... as required.
+
+
+Custom facts
+------------
+
+See existing docs, no tips here yet
+
+Custom connectors
+-----------------
+
+Check out :doc:`the writing connectors guide <./api/connectors>` for the bulk of information related to connectors.
+
+
+Exceptions
+----------
+
+pyinfra exeptions
+- raising in my code
+- handling generated by pyinfra
+
+Debugging
+---------
+
+During development a healthy scattering of ``print()``'s is possible and will output data to the screen.
+
+Despite that, its better to use the built in logging from the start. ``info`` and ``warning`` level logs are displayed by default and the log level can be
+configured.
+
+::
+  from pyinfra import logger
+  ...
+  logger.warning('{} not found in environment'.format(ke))
+  ...
+  logger.info('name is {}'.format(name))
+
+Tests
+-----
+
+Testing is covered in :doc:`Contributing <./docs/contributing>`; i haven't checked it yet
+
+

From 8ea96a21a5361a891014fdecda11cbb7122c7ca1 Mon Sep 17 00:00:00 2001
From: Karl Goetz <karl@medeopolis.au>
Date: Mon, 24 Feb 2025 13:42:27 +1100
Subject: [PATCH 2/2] Typos

---
 docs/extending.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/extending.rst b/docs/extending.rst
index 19bc4893c..361811f06 100644
--- a/docs/extending.rst
+++ b/docs/extending.rst
@@ -1,8 +1,8 @@
 Extending Pyinfra
 =================
 
-Every site needs an integration or fact whichs unique to them. The pages below here describe the process of building a pip installable pyinfra package
-with one or more custom facts, connectors, or operations.
+Every site needs an integration or fact which is unique to them. The pages below here describe the process of building a pip installable pyinfra
+package with one or more custom facts, connectors, or operations.
 
 Packaging for Pyinfra extensions
 --------------------------------
@@ -113,7 +113,7 @@ Check out :doc:`the writing connectors guide <./api/connectors>` for the bulk of
 Exceptions
 ----------
 
-pyinfra exeptions
+pyinfra exceptions
 - raising in my code
 - handling generated by pyinfra
 
@@ -135,6 +135,5 @@ configured.
 Tests
 -----
 
-Testing is covered in :doc:`Contributing <./docs/contributing>`; i haven't checked it yet
-
+Testing is covered in :doc:`Contributing <./docs/contributing>`; I haven't checked it yet