Summary

Revamp the extensions documentation.

Review Request #14542 — Created July 31, 2025 and submitted Oct. 3, 2025, 8:18 a.m.

Information

Owner

david

Repository

Review Board

Branch

release-7.1.x

Bugs

Depends On

Reviewers

Groups

reviewboard

People

Description

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 (via rbext 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).

Testing Done

Built docs and went carefully through all the pages.

Commits

Summary	ID
Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	9e7b71b864d88366f9814198d2218f0a47e9911a

Summary

Revamp the extensions documentation.

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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.

9e7b71b864d88366f9814198d2218f0a47e9911a

Issues

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 …	maubin	Aug. 7, 2025, 11:39 a.m.
It could be useful to add a section after this to explain some of the optional properties like allow_inline and …	maubin	Aug. 7, 2025, 1:45 p.m.
While you're here can you add a trailing comma here.	maubin	Aug. 7, 2025, 11:39 a.m.
And update this to renderContent() {.	maubin	Aug. 7, 2025, 11:39 a.m.
And add a trailing comma here.	maubin	Aug. 7, 2025, 11:39 a.m.
Since we already offer in house integrations with Slack and Asana, I wonder if we should replace them with different …	maubin	Aug. 7, 2025, 1:45 p.m.
Two blank lines before reference definitions.	chipx86	Aug. 8, 2025, 10:09 a.m.
This isn't returning anything.	chipx86	Aug. 8, 2025, 10:09 a.m.
This is missing the version it was added in.	chipx86	Aug. 8, 2025, 10:11 a.m.
Extra blank line here.	chipx86	Aug. 8, 2025, 10:11 a.m.
Swap these.	chipx86	Aug. 8, 2025, 10:11 a.m.
This isn't returning anything.	chipx86	Aug. 8, 2025, 10:11 a.m.
This isn't returning anything.	chipx86	Aug. 8, 2025, 10:12 a.m.
This isn't returning anything.	chipx86	Aug. 8, 2025, 10:12 a.m.
"add new features"	chipx86	Aug. 8, 2025, 10:14 a.m.
These aren't consistent with trailing periods.	chipx86	Aug. 8, 2025, 10:14 a.m.
Probably don't want to capitalize "new" here.	chipx86	Aug. 8, 2025, 10:14 a.m.
Let's say "Python Virtual Environment" (so people know this is a thing and not, like, "we put it in Docker").	chipx86	Aug. 8, 2025, 10:15 a.m.
Instead of embedding the command, it might be nice to break this out into a separate code block.	chipx86	Aug. 8, 2025, 10:15 a.m.
This is missing a leading $ for the prompt styling.	chipx86	Aug. 8, 2025, 10:15 a.m.
I believe we normally use 4 space indentation inside definition lists.	chipx86	Aug. 8, 2025, 10:16 a.m.
The PEP won't mean much to anybody but us. If we reference it, we should probably just link it.	chipx86	Aug. 8, 2025, 10:17 a.m.
Let's call it the "Review Board devserver".	chipx86	Aug. 8, 2025, 10:16 a.m.
We always define references at the bottom of the section block, separated by two blank lines on either side.	chipx86	Aug. 21, 2025, 8:15 a.m.
Single backticks are an error. This should either be double or, more likely, a reference.	chipx86	Aug. 21, 2025, 8:16 a.m.

flake8 passed.

JSHint passed.

docs/manual/extending/extensions/hooks/api-extra-data-access-hook.rst (Diff revision 1)

The issue has been resolved. Show all issues

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.

david Aug. 7, 2025, 1:51 p.m.

Might as well. There aren't that many code blocks.

docs/manual/extending/extensions/review-ui.rst (Diff revision 1)

The issue has been resolved. Show all issues

It could be useful to add a section after this to explain some of the optional properties like allow_inline and supports_diffing.

david Aug. 7, 2025, 1:51 p.m.

I think expanding that particular doc is outside the scope here. I'll make sure this is tracked, though.

maubin Oct. 1, 2025, 12:33 a.m.
```
I take care of this in /r/14626/.
```

docs/manual/extending/extensions/review-ui.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
While you're here can you add a trailing comma here.
```
docs/manual/extending/extensions/review-ui.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
And update this to renderContent() {.
```
docs/manual/extending/extensions/review-ui.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
And add a trailing comma here.
```

docs/manual/extending/index.rst (Diff revision 1)

The issue has been resolved. Show all issues

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
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	575962bebcb7a14c5d05c145cfc77466843c94db
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	e10f883f91c4b60ccfd3de5eb9f5b233ea8724c6

Diff:

Revision 2 (+1774 -1048)

Show changes

	docs/manual/extending/auth-backends.rst
	docs/manual/extending/index.rst
	docs/manual/extending/extensions/configuration.rst
	docs/manual/extending/extensions/distribution.rst
	docs/manual/extending/extensions/file-layout.rst
	docs/manual/extending/extensions/js-extensions.rst
	docs/manual/extending/extensions/models.rst
	docs/manual/extending/extensions/review-request-fields.rst
	38 more

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

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.

david Aug. 8, 2025, 10:44 a.m.

Broke a lot of that out into a new page.

docs/manual/extending/extensions/file-layout.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
Two blank lines before reference definitions.
```
docs/manual/extending/extensions/hooks/email-hook.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
This isn't returning anything.
```
docs/manual/extending/extensions/hooks/hide-action-hook.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
This is missing the version it was added in.
```
docs/manual/extending/extensions/hooks/hide-action-hook.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
Extra blank line here.
```
docs/manual/extending/extensions/hooks/integration-hook.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
Swap these.
```

docs/manual/extending/extensions/hooks/review-published-email-hook.rst (Diff revision 2)

The issue has been resolved. Show all issues

This isn't returning anything.

docs/manual/extending/extensions/hooks/review-reply-published-email-hook.rst (Diff revision 2)

The issue has been resolved. Show all issues

This isn't returning anything.

docs/manual/extending/extensions/hooks/review-request-published-email-hook.rst (Diff revision 2)

The issue has been resolved. Show all issues

This isn't returning anything.

docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
"add new features"
```
docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
These aren't consistent with trailing periods.
```
docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
Probably don't want to capitalize "new" here.
```

docs/manual/extending/index.rst (Diff revision 2)

The issue has been resolved. Show all issues

Let's say "Python Virtual Environment" (so people know this is a thing and not, like, "we put it in Docker").

docs/manual/extending/index.rst (Diff revision 2)

The issue has been resolved. Show all issues

Instead of embedding the command, it might be nice to break this out into a separate code block.

docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
This is missing a leading $ for the prompt styling.
```
docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
I believe we normally use 4 space indentation inside definition lists.
```

docs/manual/extending/index.rst (Diff revision 2)

The issue has been resolved. Show all issues

The PEP won't mean much to anybody but us. If we reference it, we should probably just link it.

docs/manual/extending/index.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
Let's call it the "Review Board devserver".
```

Commits:

	Summary	ID
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	e10f883f91c4b60ccfd3de5eb9f5b233ea8724c6
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	1c789632b15b1ea8133d96e759d9e873f677c42a

Diff:

Revision 3 (+1912 -1104)

Show changes

	docs/manual/extending/auth-backends.rst
	docs/manual/extending/index.rst
	docs/manual/extending/extensions/configuration.rst
	docs/manual/extending/extensions/distribution.rst
	docs/manual/extending/extensions/file-layout.rst
	docs/manual/extending/extensions/js-extensions.rst
	docs/manual/extending/extensions/making-an-extension.rst
	docs/manual/extending/extensions/models.rst
	39 more

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

docs/manual/extending/extensions/making-an-extension.rst (Diff revision 3)

The issue has been resolved. Show all issues

We always define references at the bottom of the section block, separated by two blank lines on either side.

docs/manual/extending/extensions/making-an-extension.rst (Diff revision 3)
The issue has been resolved. Show all issues
```
Single backticks are an error. This should either be double or, more likely, a reference.
```

Commits:

	Summary	ID
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	1c789632b15b1ea8133d96e759d9e873f677c42a
	Revamp the extensions documentation. 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 (via `rbext 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). Testing Done: Built docs and went carefully through all the pages.	9e7b71b864d88366f9814198d2218f0a47e9911a

Diff:

Revision 4 (+1914 -1104)

Show changes

	docs/manual/extending/auth-backends.rst
	docs/manual/extending/index.rst
	docs/manual/extending/extensions/configuration.rst
	docs/manual/extending/extensions/distribution.rst
	docs/manual/extending/extensions/file-layout.rst
	docs/manual/extending/extensions/js-extensions.rst
	docs/manual/extending/extensions/making-an-extension.rst
	docs/manual/extending/extensions/models.rst
	39 more

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-7.1.x (c2b01aa)