Revamp the extensions documentation.

Review Request #14542 — Created July 31, 2025 and updated

Information

Review Board
release-7.1.x

Reviewers

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).

Built docs and went carefully through all the pages.

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
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 …

maubinmaubin

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

maubinmaubin

While you're here can you add a trailing comma here.

maubinmaubin

And update this to renderContent() {.

maubinmaubin

And add a trailing comma here.

maubinmaubin

Since we already offer in house integrations with Slack and Asana, I wonder if we should replace them with different …

maubinmaubin

Two blank lines before reference definitions.

chipx86chipx86

This isn't returning anything.

chipx86chipx86

This is missing the version it was added in.

chipx86chipx86

Extra blank line here.

chipx86chipx86

Swap these.

chipx86chipx86

This isn't returning anything.

chipx86chipx86

This isn't returning anything.

chipx86chipx86

This isn't returning anything.

chipx86chipx86

"add new features"

chipx86chipx86

These aren't consistent with trailing periods.

chipx86chipx86

Probably don't want to capitalize "new" here.

chipx86chipx86

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

chipx86chipx86

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

chipx86chipx86

This is missing a leading $ for the prompt styling.

chipx86chipx86

I believe we normally use 4 space indentation inside definition lists.

chipx86chipx86

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

chipx86chipx86

Let's call it the "Review Board devserver".

chipx86chipx86

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

chipx86chipx86

Single backticks are an error. This should either be double or, more likely, a reference.

chipx86chipx86
maubin
  1. 
      
  2. 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.

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

  3. 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.

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

    2. I take care of this in /r/14626/.

  4. Show all issues

    While you're here can you add a trailing comma here.

  5. Show all issues

    And update this to renderContent() {.

  6. Show all issues

    And add a trailing comma here.

  7. docs/manual/extending/index.rst (Diff revision 1)
     
     
    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.

  8. 
      
david
chipx86
  1. 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.

    1. Broke a lot of that out into a new page.

  2. docs/manual/extending/extensions/file-layout.rst (Diff revision 2)
     
     
     
     
    Show all issues

    Two blank lines before reference definitions.

  3. Show all issues

    This isn't returning anything.

  4. Show all issues

    This is missing the version it was added in.

  5. Show all issues

    Extra blank line here.

  6. Show all issues

    Swap these.

  7. Show all issues

    This isn't returning anything.

  8. Show all issues

    This isn't returning anything.

  9. Show all issues

    This isn't returning anything.

  10. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

    "add new features"

  11. docs/manual/extending/index.rst (Diff revision 2)
     
     
     
     
     
     
     
    Show all issues

    These aren't consistent with trailing periods.

  12. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

    Probably don't want to capitalize "new" here.

  13. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

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

  14. docs/manual/extending/index.rst (Diff revision 2)
     
     
     
     
    Show all issues

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

  15. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

    This is missing a leading $ for the prompt styling.

  16. docs/manual/extending/index.rst (Diff revision 2)
     
     
     
     
     
    Show all issues

    I believe we normally use 4 space indentation inside definition lists.

  17. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

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

  18. docs/manual/extending/index.rst (Diff revision 2)
     
     
    Show all issues

    Let's call it the "Review Board devserver".

  19. 
      
david
maubin
  1. Ship It!
  2. 
      
chipx86
  1. 
      
  2. Show all issues

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

  3. Show all issues

    Single backticks are an error. This should either be double or, more likely, a reference.

  4. 
      
david
Review request changed
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

Checks run (2 succeeded)

flake8 passed.
JSHint passed.
maubin
  1. Ship It!
  2.