diff --git a/.gitignore b/.gitignore
index 5949200045..4c3312af1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 /*
 !/.gitignore
+!/.yardopts
 !/Library/
 !/CODEOFCONDUCT.md
 !/CONTRIBUTING.md
diff --git a/.yardopts b/.yardopts
new file mode 100644
index 0000000000..6a40e6cace
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1,4 @@
+--title "Homebrew"
+--main Library/Homebrew/API.md
+Library/Homebrew/**/*.rb
+*.md
diff --git a/Library/Homebrew/.rdoc_options b/Library/Homebrew/.rdoc_options
deleted file mode 100644
index b953b9e3b6..0000000000
--- a/Library/Homebrew/.rdoc_options
+++ /dev/null
@@ -1,17 +0,0 @@
---- !ruby/object:RDoc::Options
-encoding: UTF-8
-static_path: []
-rdoc_include:
-- .
-charset: UTF-8
-exclude:
-hyperlink_all: false
-line_numbers: true
-main_page:
-markup: rdoc
-page_dir:
-show_hash: false
-tab_width: 2
-title: Homebrew
-visibility: :protected
-webcvs:
diff --git a/Library/Homebrew/API.md b/Library/Homebrew/API.md
new file mode 100644
index 0000000000..f154675e2d
--- /dev/null
+++ b/Library/Homebrew/API.md
@@ -0,0 +1,4 @@
+# Homebrew Public API
+We're (finally) working on a documented public API for Homebrew. It's currently a work in progress; a bunch of public stuff is documented and a bunch of private stuff is undocumented. Sorry about that!
+
+The main class you should look at is {Formula}. Assume everything else is private for now.