Revamp the extensions documentation.
Review Request #14542 — Created July 31, 2025 and updated
Our extensions framework actually had pretty decent documentation, but
it was quite poorly organized.This change revamps things, primarily the main "Extending Review Board"
page.That page used to just be a set of links to detailed reference pages and
a huge list of individual hooks. It's now much more of a tutorial, going
through the basic steps of setting up a development environment,
creating the extension boilerplate (viarbext create
), installing that
package in editable mode, activating it, and then the basics of hooks
and API resources.The list of full examples is now more prominent, coming immediately
after those initial steps.The "Extension Basics" section has been renamed to "Extension
Reference", and the toctree has been given one more level, letting
people see what's inside each of those pages (since some of those have a
lot of specific detail which may not be immediately obvious from the
title).The list of hooks has been moved into its own page and reorganized to
hopefully be a bit clearer. The descriptions for each hook are generally
simplified but also expanded a bit in cases where it's a bit more niche
(such as approval and diff ACLs).
Built docs and went carefully through all the pages.
Summary | ID |
---|---|
9e7b71b864d88366f9814198d2218f0a47e9911a |
Description | From | Last Updated |
---|---|---|
It'd be nice to add typing to all the rest of the code examples in our extension docs, but that … |
![]() |
|
It could be useful to add a section after this to explain some of the optional properties like allow_inline and … |
![]() |
|
While you're here can you add a trailing comma here. |
![]() |
|
And update this to renderContent() {. |
![]() |
|
And add a trailing comma here. |
![]() |
|
Since we already offer in house integrations with Slack and Asana, I wonder if we should replace them with different … |
![]() |
|
Two blank lines before reference definitions. |
|
|
This isn't returning anything. |
|
|
This is missing the version it was added in. |
|
|
Extra blank line here. |
|
|
Swap these. |
|
|
This isn't returning anything. |
|
|
This isn't returning anything. |
|
|
This isn't returning anything. |
|
|
"add new features" |
|
|
These aren't consistent with trailing periods. |
|
|
Probably don't want to capitalize "new" here. |
|
|
Let's say "Python Virtual Environment" (so people know this is a thing and not, like, "we put it in Docker"). |
|
|
Instead of embedding the command, it might be nice to break this out into a separate code block. |
|
|
This is missing a leading $ for the prompt styling. |
|
|
I believe we normally use 4 space indentation inside definition lists. |
|
|
The PEP won't mean much to anybody but us. If we reference it, we should probably just link it. |
|
|
Let's call it the "Review Board devserver". |
|
|
We always define references at the bottom of the section block, separated by two blank lines on either side. |
|
|
Single backticks are an error. This should either be double or, more likely, a reference. |
|

-
-
It'd be nice to add typing to all the rest of the code examples in our extension docs, but that is a tedious job and not super necessary for this change.
-
It could be useful to add a section after this to explain some of the optional properties like
allow_inline
andsupports_diffing
. -
-
-
-
Since we already offer in house integrations with Slack and Asana, I wonder if we should replace them with different examples here.
Could even be nice to say "AI chat bots" here.
- Commits:
-
Summary ID 575962bebcb7a14c5d05c145cfc77466843c94db e10f883f91c4b60ccfd3de5eb9f5b233ea8724c6 - Diff:
-
Revision 2 (+1774 -1048)
Checks run (2 succeeded)
-
I think this looks great. Love the new introduction. I think the one thing I'm uncertain about is how much of the introduction lives on the front page. If I'm building an extension and want to find references, there's a lot to sort through to get to it. It might be better to keep the bulk of the steps for creating/activating/testing on a Getting Started page.
-
-
-
-
-
-
-
-
-
-
-
-
Let's say "Python Virtual Environment" (so people know this is a thing and not, like, "we put it in Docker").
-
-
-
-
-
- Commits:
-
Summary ID e10f883f91c4b60ccfd3de5eb9f5b233ea8724c6 1c789632b15b1ea8133d96e759d9e873f677c42a - Diff:
-
Revision 3 (+1912 -1104)
Checks run (2 succeeded)
- Commits:
-
Summary ID 1c789632b15b1ea8133d96e759d9e873f677c42a 9e7b71b864d88366f9814198d2218f0a47e9911a - Diff:
-
Revision 4 (+1914 -1104)