Docs build 2025-01-09

Author: github-actions

en/latest/_sources/api/facts.md.txt

@@ -0,0 +1,96 @@
+# Writing Facts
+
+[Facts](../facts) are written as Python classes. They provide a ``command`` (as either a string or method)
+and a ``process`` function. The command is executed on the target host and the output
+passed (as a ``list`` of lines) to the ``process`` handler to generate fact data. Facts can output anything, normally a ``list`` or ``dict``.
+
+Fact classes may provide a ``default`` function that takes no arguments (except ``self``). The return value of this function is used if an error
+occurs during fact collection. Additionally, a ``requires_command`` variable can be set on the fact that specifies a command that must be available
+on the host to collect the fact. If this command is not present on the host, the fact will be set to the default, or empty if no ``default`` function
+is available.
+
+### Importing & Using Facts
+
+Like operations, facts are imported from Python modules and executed by calling `Host.get_fact`. For example:
+
+```py
+from pyinfra import host
+from pyinfra.facts.server import Which
+
+host.get_fact(Which, command='htop')
+```
+
+### Example: getting swap status
+
+This fact returns a boolean indicating whether swap is enabled. For this fact the ``command`` is declared as a class attribute.
+
+```py
+from  pyinfra.api import FactBase
+
+class SwapEnabled(FactBase):
+    '''
+    Returns a boolean indicating whether swap is enabled.
+    '''
+
+    command = 'swapon --show'
+
+    def process(self, output):
+        return len(output) > 0  # we have one+ lines
+```
+
+This fact could then be used like so:
+
+```py
+is_swap_enabled = host.get_fact(SwapEnabled)
+```
+
+### Example: getting the list of files in a directory
+
+This fact returns a list of files found in a given directory. For this fact the ``command`` is declared as a class method, indicating the fact takes arguments.
+
+```py
+from pyinfra.api import FactBase
+
+class FindFiles(FactBase):
+    '''
+    Returns a list of files from a start point, recursively using find.
+    '''
+
+    def command(self, path):
+        # Find files in the given location
+        return 'find {0} -type f'.format(path)
+
+    def process(self, output):
+        return output  # return the list of lines (files) as-is
+```
+
+This fact could then be used like so:
+
+```py
+list_of_files = host.get_fact(FindFiles, path='/somewhere')
+```
+
+### Example: getting any output from a command
+
+This fact returns the raw output of any command. For this fact the ``command`` is declared as a class method, indicating the fact takes arguments.
+
+```py
+from pyinfra.api import FactBase
+
+class RawCommandOutput(FactBase):
+    '''
+    Returns the raw output of a command.
+    '''
+
+    def command(self, command):
+        return command
+
+    def process(self, output):
+        return '\n'.join(output)  # re-join and return the output lines
+```
+
+This fact could then be used like so:
+
+```py
+command_output = host.get_fact(RawCommandOutput, command='execute this command')
+```

en/latest/_sources/api/index.rst.txt

@@ -6,12 +6,12 @@ In addition to :doc:`the pyinfra CLI <../cli>`, pyinfra provides a full Python A
 You can also reference `pyinfra's own main.py <https://github.com/pyinfra-dev/pyinfra/blob/3.x/pyinfra_cli/main.py>`_, and the `pyinfra API source code <https://github.com/pyinfra-dev/pyinfra/tree/3.x/pyinfra/api>`_.
 
 Full Example
-============
+------------
 
 `A full example of how to use the API can be found here <https://github.com/pyinfra-dev/pyinfra-examples/blob/main/.old/api_deploy.py>`_. (Note: this is not yet tested and is pending future updates)
 
 Basic Localhost Example
-=======================
+-----------------------
 
 .. code:: python
 

en/latest/_sources/api/operations.md.txt

@@ -1,8 +1,4 @@
-# Writing Facts & Operations
-
-Operations & facts are the building blocks pyinfra uses to make changes to hosts. This document describes how you can write your own to extend pyinfra's functionality.
-
-## Operations
+# Writing Operations
 
 [Operations](../operations) are defined as Python functions. They are passed the current deploy state, the target host, and any operation arguments. Operation functions read state from the host, compare it to the arguments, and yield commands.
 
@@ -82,100 +78,3 @@ def file(name, present=True):
     elif info and not present:
         yield "rm -f {0}".format(name)
 ```
-
-## Facts
-
-[Facts](../facts) are written as Python classes. They provide a ``command`` (as either a string or method)
-and a ``process`` function. The command is executed on the target host and the output
-passed (as a ``list`` of lines) to the ``process`` handler to generate fact data. Facts can output anything, normally a ``list`` or ``dict``.
-
-Fact classes may provide a ``default`` function that takes no arguments (except ``self``). The return value of this function is used if an error
-occurs during fact collection. Additionally, a ``requires_command`` variable can be set on the fact that specifies a command that must be available
-on the host to collect the fact. If this command is not present on the host, the fact will be set to the default, or empty if no ``default`` function
-is available.
-
-### Importing & Using Facts
-
-Like operations, facts are imported from Python modules and executed by calling `Host.get_fact`. For example:
-
-```py
-from pyinfra import host
-from pyinfra.facts.server import Which
-
-host.get_fact(Which, command='htop')
-```
-
-### Example: getting swap status
-
-This fact returns a boolean indicating whether swap is enabled. For this fact the ``command`` is declared as a class attribute.
-
-```py
-from  pyinfra.api import FactBase
-
-class SwapEnabled(FactBase):
-    '''
-    Returns a boolean indicating whether swap is enabled.
-    '''
-
-    command = 'swapon --show'
-
-    def process(self, output):
-        return len(output) > 0  # we have one+ lines
-```
-
-This fact could then be used like so:
-
-```py
-is_swap_enabled = host.get_fact(SwapEnabled)
-```
-
-### Example: getting the list of files in a directory
-
-This fact returns a list of files found in a given directory. For this fact the ``command`` is declared as a class method, indicating the fact takes arguments.
-
-```py
-from pyinfra.api import FactBase
-
-class FindFiles(FactBase):
-    '''
-    Returns a list of files from a start point, recursively using find.
-    '''
-
-    def command(self, path):
-        # Find files in the given location
-        return 'find {0} -type f'.format(path)
-
-    def process(self, output):
-        return output  # return the list of lines (files) as-is
-```
-
-This fact could then be used like so:
-
-```py
-list_of_files = host.get_fact(FindFiles, path='/somewhere')
-```
-
-### Example: getting any output from a command
-
-This fact returns the raw output of any command. For this fact the ``command`` is declared as a class method, indicating the fact takes arguments.
-
-```py
-from pyinfra.api import FactBase
-
-class RawCommandOutput(FactBase):
-    '''
-    Returns the raw output of a command.
-    '''
-
-    def command(self, command):
-        return command
-
-    def process(self, output):
-        return '\n'.join(output)  # re-join and return the output lines
-```
-
-This fact could then be used like so:
-
-```py
-command_output = host.get_fact(RawCommandOutput, command='execute this command')
-```

en/latest/_sources/connectors/docker.rst.txt

@@ -1,11 +1,18 @@
 ``@docker`` Connector
 ---------------------
 
-The docker connector allows you to build Docker images or modify running
-Docker containers. You can pass either an image name or existing container ID:
+The Docker connector allows you to use pyinfra to create new Docker images or modify running
+Docker containers.
 
-+ Image - will create a new container from the image, execute operations         against it, save into a new Docker image and remove the container
-+ Existing container ID - will execute operations against the running         container, leaving it running
+.. note::
+
+    The Docker connector allows pyinfra to target Docker containers as inventory and is
+    unrelated to the :doc:`../operations/docker` & :doc:`../facts/docker`.
+
+You can pass either an image name or existing container ID:
+
++ Image - will create a new container from the image, execute operations against it, save into         a new Docker image and remove the container
++ Existing container ID - will execute operations against the running container, leaving it         running
 
 .. code:: shell
 
@@ -18,6 +25,10 @@ Docker containers. You can pass either an image name or existing container ID:
     # Execute against a running container
     pyinfra @docker/2beb8c15a1b1 ...
 
+The Docker connector is great for testing pyinfra operations locally, rather than connecting to
+a remote host over SSH each time. This gives you a fast, local-first devloop to iterate on when
+writing deploys, operations or facts.
+
 Usage
 ~~~~~
 

en/latest/_sources/contributing.md.txt

@@ -7,7 +7,7 @@ Third party pull requests help expand pyinfra's functionality and are essential
 ## Guides
 
 + [How to write operations](api/operations)
-+ [How to write facts](api/operations.md#facts)
++ [How to write facts](api/facts)
 + [How to write connectors](api/connectors)
 + [API reference](api/reference)
 
@@ -46,10 +46,6 @@ GitHub will run all the test suites as part of any pull requests. There's a hand
 scripts/dev-test.sh
 ```
 
-#### Unit Tests
-
-Use `pytest` to run the unit tests, or `pytest --cov` to run with coverage. Pull requests are expected to be tested and not drop overall project coverage by >1%.
-
 To limit the pytests to a specific fact or operation:
 
 ```sh
@@ -65,6 +61,9 @@ pytest tests/test_operations.py -k "selinux."
 The end to end tests are also executed via `pytest` but not selected by default, options/usage:
 
 ```sh
+# Run all the e2e tests (local, SSH, Docker)
+scripts/dev-test-e2e.sh
+
 # Run local e2e tests (works on Linux / MacOS, no Windows yet)
 pytest -m end_to_end_local
 
@@ -78,11 +77,11 @@ pytest -m end_to_end_docker
 To generate:
 
 ```sh
-sphinx-build -a docs/ docs/build/
+scripts/build-public-docs.sh
 ```
 
 To view ([localhost:8000](http://localhost:8000)):
 
 ```sh
-python -m http.server -d docs/build/
+python -m http.server -d docs/public/en/latest/
 ```

en/latest/_sources/facts/crontab.rst.txt

@@ -15,6 +15,7 @@ See also: :doc:`../operations/crontab`.
 Returns a dictionary of CrontabFile.
 
 .. code:: python
+
     # CrontabFile.items()
     {
         "/path/to/command": {

en/latest/_sources/facts/docker.rst.txt

@@ -1,6 +1,11 @@
 Docker Facts
 ------------
 
+
+Facts about Docker containers, volumes and networks. These facts give you information from the view
+of the current inventory host. See the :doc:`../connectors/docker` to use Docker containers as
+inventory directly.
+
 See also: :doc:`../operations/docker`.
 
 .. _facts:docker.DockerContainer:

en/latest/_sources/index.rst.txt

@@ -40,14 +40,6 @@ Using pyinfra
 Deploy Reference
 ----------------
 
-.. compound::
-    :doc:`examples`
-        A set of documented example deploys that focus on common patterns and use-cases.
-
-.. compound::
-    :doc:`connectors`
-        A list of connectors to target different hosts such as ``@docker``, ``@local`` and ``@terraform``.
-
 .. compound::
     :doc:`operations`
         A list of all available operations and their arguments, e.g. ``apt.packages``.
@@ -56,6 +48,10 @@ Deploy Reference
     :doc:`facts`
         A list of all facts pyinfra can gather from hosts, e.g. ``server.Hostname``.
 
+.. compound::
+    :doc:`connectors`
+        A list of connectors to target different hosts such as ``@docker``, ``@local`` and ``@terraform``.
+
 
 How pyinfra Works
 -----------------
@@ -74,7 +70,11 @@ How pyinfra Works
 
 .. compound::
     :doc:`api/operations`
-        How to write your own facts & operations for pyinfra.
+        How to write your own operations for pyinfra.
+
+.. compound::
+    :doc:`api/facts`
+        How to write your own facts for pyinfra.
 
 .. compound::
     :doc:`api/index`
@@ -97,19 +97,19 @@ How pyinfra Works
     :maxdepth: 1
     :caption: Deploy Reference
 
-    examples
-    connectors
     operations
     facts
+    connectors
 
 .. toctree::
     :hidden:
     :caption: How pyinfra Works
 
     deploy-process
     api/deploys
-    api/connectors
     api/operations
+    api/facts
+    api/connectors
     api/index
 
 .. toctree::