diff --git a/docs/conf.py b/docs/conf.py
index 43e165380..7db3cb2fe 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -5,6 +5,7 @@
import guzzle_sphinx_theme
from pyinfra import __version__, local
+from pyinfra.api import metadata
copyright = "Nick Barrett {0} — pyinfra v{1}".format(
date.today().year,
@@ -57,9 +58,42 @@
]
+def rstjinja(app, docname, source):
+ """
+ Render certain pages as a jinja templates.
+ """
+ # this should only be run when building html
+ if app.builder.format != "html":
+ return
+ # We currently only render docs/operations.rst
+ # and docs/facts.rst as jinja2 templates
+ if docname in ["operations", "facts"]:
+ src = source[0]
+ rendered = app.builder.templates.render_string(src, app.config.html_context)
+ source[0] = rendered
+
+
def setup(app):
+ app.connect("source-read", rstjinja)
this_dir = path.dirname(path.realpath(__file__))
scripts_dir = path.abspath(path.join(this_dir, "..", "scripts"))
+ metadata_file = path.abspath(path.join(this_dir, "..", "pyinfra-metadata.toml"))
+ if not path.exists(metadata_file):
+ raise ValueError("No pyinfra-metadata.toml in project root")
+ with open(metadata_file, "r") as file:
+ metadata_text = file.read()
+ plugins = metadata.parse_plugins(metadata_text)
+
+ operation_plugins = sorted([p for p in plugins if p.type == "operation"], key=lambda p: p.name)
+ fact_plugins = sorted([p for p in plugins if p.type == "fact"], key=lambda p: p.name)
+ html_context = {
+ "operation_plugins": operation_plugins,
+ "fact_plugins": fact_plugins,
+ "tags": metadata.ALLOWED_TAGS,
+ "docs_language": language,
+ "docs_version": version,
+ }
+ app.config.html_context = html_context
for auto_docs_name in ("operations", "facts", "apidoc", "connectors"):
auto_docs_path = path.join(this_dir, auto_docs_name)
diff --git a/docs/connectors.rst b/docs/connectors.rst
index 3970b166d..9f3a51cc1 100644
--- a/docs/connectors.rst
+++ b/docs/connectors.rst
@@ -1,6 +1,14 @@
Connectors Index
================
+.. raw:: html
+
+
+
Connectors enable pyinfra to integrate with other tools out of the box. Connectors can do one of three things:
+ Implement how commands are executed (``@ssh``, ``@local``)
diff --git a/docs/facts.rst b/docs/facts.rst
index 6d9261a57..9dd40faca 100644
--- a/docs/facts.rst
+++ b/docs/facts.rst
@@ -1,6 +1,14 @@
Facts Index
===========
+.. raw:: html
+
+
+
pyinfra uses **facts** to determine the existing state of a remote server. Operations use this information to generate commands which alter the state. Facts are read-only and are populated at the beginning of the deploy.
Facts can be executed/tested via the command line:
@@ -35,26 +43,60 @@ You can leverage facts within :doc:`operations ` like this:
**Want a new fact?** Check out :doc:`the writing facts guide <./api/operations>`.
-Facts, like :doc:`operations `, are namespaced as different modules - shortcuts to each of these can be found in the sidebar.
-
.. raw:: html
-
+
+{% for tag in plugin.tags %}
+ {{ tag.title_case }}
+{% endfor %}
+
+
+
+{% endfor %}
+
+
+
.. toctree::
:maxdepth: 2
:glob:
+ :hidden:
facts/*
diff --git a/docs/operations.rst b/docs/operations.rst
index ba6a6c579..8d5c544b8 100644
--- a/docs/operations.rst
+++ b/docs/operations.rst
@@ -1,56 +1,73 @@
Operations Index
================
-Operations are used to describe changes to make to systems in the inventory. Use them to define state and pyinfra will make any necessary changes to reach that state. All operations accept a set of :doc:`global arguments ` and are grouped as Python modules.
-
-**Want a new operation?** Check out :doc:`the writing operations guide <./api/operations>`.
-
.. raw:: html
-
Popular operations by category
-
-.. admonition:: Basics
- :class: note inline
-
- :doc:`operations/files`, :doc:`operations/server`, :doc:`operations/git`, :doc:`operations/systemd`
-
-.. admonition:: System Packages
- :class: note inline
-
- :doc:`operations/apt`, :doc:`operations/apk`, :doc:`operations/brew`, :doc:`operations/dnf`, :doc:`operations/yum`
+
-.. admonition:: Language Packages
- :class: note inline
-
- :doc:`operations/gem`, :doc:`operations/npm`, :doc:`operations/pip`
-
-.. admonition:: Databases
- :class: note inline
-
- :doc:`operations/postgresql`, :doc:`operations/mysql`
-
-.. raw:: html
+Operations are used to describe changes to make to systems in the inventory. Use them to define state and pyinfra will make any necessary changes to reach that state. All operations accept a set of :doc:`global arguments ` and are grouped as Python modules.
-
All operations alphabetically
+**Want a new operation?** Check out :doc:`the writing operations guide <./api/operations>`.
.. raw:: html
-
+