From 35b618c2eb5bb893e06b45f44814dcce20901968 Mon Sep 17 00:00:00 2001
From: Vinnie Magro <vmagro@meta.com>
Date: Wed, 1 Nov 2023 12:40:34 -0700
Subject: [PATCH] [antlir2][docs] document chef-solo and a few other features

Summary: We need better docs

Test Plan: debugging_without_docs

Reviewed By: epilatow

Differential Revision: D50885410

fbshipit-source-id: 799a38963a2822b363b09cda0075e0bf038c04b2
---
 .../docs/docs/features/_category_.json        |  5 ++
 antlir/antlir2/docs/docs/features/features.md | 71 +++++++++++++++++++
 .../antlir2/docs/docs/recipes/_category_.json |  2 +-
 3 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 antlir/antlir2/docs/docs/features/_category_.json
 create mode 100644 antlir/antlir2/docs/docs/features/features.md

diff --git a/antlir/antlir2/docs/docs/features/_category_.json b/antlir/antlir2/docs/docs/features/_category_.json
new file mode 100644
index 00000000000..73d5b0f5798
--- /dev/null
+++ b/antlir/antlir2/docs/docs/features/_category_.json
@@ -0,0 +1,5 @@
+{
+    "label": "Features",
+    "position": 20,
+    "collapsed": false
+}
diff --git a/antlir/antlir2/docs/docs/features/features.md b/antlir/antlir2/docs/docs/features/features.md
new file mode 100644
index 00000000000..3795fae55a6
--- /dev/null
+++ b/antlir/antlir2/docs/docs/features/features.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 1
+---
+
+# Features
+
+"Features" is the term that `antlir2` uses to describe user-provided
+instructions for how an image is to be built.
+
+A common misconception is that the order in which features are written in buck
+matter. They do not. Features are ordered by a
+[dependency graph](../internals/depgraph.md), so you don't have to concern
+yourself with the order in which you write your features.
+
+## Self-explanatory features
+
+:::note
+
+In the near future, this section will be replaced with an auto-generated section
+with the actual buck api docs.
+
+:::
+
+### `feature.install`
+
+Install a source file/directory (or output of a buck rule) into the image
+
+### `feature.ensure_dirs_exist`
+
+Create an entire directory chain owned by the same `user:group` and the same
+mode bits
+
+### `feature.ensure_subdirs_exist`
+
+Create some directories under an existing directory, where only the `user:group`
+and mode bits of the `subdirs_to_create` matter, as long as the parent
+directories exist.
+
+### `feature.genrule`
+
+Run an arbitrary command inside the image as any user that exists in the image.
+This cannot provide you any of the safety that `antlir2` normally provides, so
+should be used as a last resort.
+
+### `feature.remove`
+
+Delete a file/directory.
+
+### `feature.ensure_(file|dir)_symlink`
+
+Create a symlink to a file or directory.
+
+### `feature.rpms_install`
+
+Install RPMs by name, nevra or `.rpm` artifact.
+
+### `feature.rpms_upgrade`
+
+Upgrade RPMs to the newest allowed version.
+
+### `feature.rpms_remove_if_exists`
+
+Remove RPMs by name or nevra if they are installed.
+
+### `feature.(user|group)_add`
+
+Add a new user/group to `/etc/passwd` and friends.
+
+<InternalOnly>
+There are also some <a href="./fb">Meta-only internal features</a>
+</InternalOnly>
diff --git a/antlir/antlir2/docs/docs/recipes/_category_.json b/antlir/antlir2/docs/docs/recipes/_category_.json
index 6210b7a9dff..4ee38a6c650 100644
--- a/antlir/antlir2/docs/docs/recipes/_category_.json
+++ b/antlir/antlir2/docs/docs/recipes/_category_.json
@@ -1,5 +1,5 @@
 {
     "label": "Recipes",
-    "position": 20,
+    "position": 30,
     "collapsed": false
 }