Docs for URL,Dashboard,NavigationBar-Hooks
Review Request #3617 — Created Dec. 3, 2012 and submitted
Extensions documentation for URLHook, DashboardHook, and NavigationBarHook.
Ran `make html` in reviewboard/docs/codebase/ No error output from sphinx. Rendered HTML pass visual inspection.
| Description | From | Last Updated |
|---|---|---|
|
These are only really useful if we're actively linking to them. |
 chipx86
|
|
|
"Review Board" |
chipx86
|
|
|
Hooks aren't really there to help "customize" Extensions - they're there to give extensions a means to customize Review Board. … |
 mike_conley
|
|
|
"Review Board" |
chipx86
|
|
|
"We briefly examine a few...demonstrage usage with sample code" - on tone, sounds a bit text-bookish. Maybe instead, simply: "The … |
mike_conley
|
|
|
We can make this even more general - "URLHooks are used to extend the URL patterns that Review Board will … |
mike_conley
|
|
|
This last sentence is generally true for all hooks - maybe you won't need it if you add that sentence … |
mike_conley
|
|
|
"once is" -> "once" |
chipx86
|
|
|
SampleExtension ? Probably don't need to capitalize "Dashboard." Is this example meant to tie in with the DashboardHook? If so, … |
chipx86
|
|
|
Alignment error. |
chipx86
|
|
|
"dashboard page" ? |
chipx86
|
|
|
"on the dashboard's navigation pane." |
chipx86
|
|
|
"dashboard page." |
chipx86
|
|
|
"extension" "dashboard page" |
chipx86
|
|
|
I think it's better to make this one statement. |
chipx86
|
|
|
Blank line above. |
chipx86
|
|
|
Make sure the indentation inside the template tags are correct: {% block content %} {% box "reports" %} |
chipx86
|
|
|
Instead of "To do..." how about something like, "This is my new Dashboard page for Review Board!" That way, it … |
mike_conley
|
|
|
Probably want a blank line between these. |
chipx86
|
|
|
End with a period. |
chipx86
|
|
|
It'd be nice to just pass the entries in here directly. |
chipx86
|
|
|
They don't use them as a primary mechanism, they *are* a primary mechanism. I'd be OK with "Extensions can use … |
mike_conley
|
|
|
Let's say this: Notice how sample_extension.urls was included in the patterns. In this case, sample_extension is the package name for … |
mike_conley
|
|
|
"it then" -> "then it" |
mike_conley
|
|
|
This looks like leftover cruft to be removed. |
mike_conley
|
-
Great to see some documentation! Just a few suggestions below.
-
Hooks aren't really there to help "customize" Extensions - they're there to give extensions a means to customize Review Board. They're one of the primary mechanisms for changing the appearance and behaviour of Review Board.
-
"We briefly examine a few...demonstrage usage with sample code" - on tone, sounds a bit text-bookish. Maybe instead, simply: "The following hooks are available for extensions to use." You might want to mention that hooks need only be instantiated for Review Board to "notice" them, and that these hooks are automatically removed when the extension shuts down.
-
We can make this even more general - "URLHooks are used to extend the URL patterns that Review Board will recognize and respond to."
-
This last sentence is generally true for all hooks - maybe you won't need it if you add that sentence in the parent section - that hooks need only be instantiated to work, and will be automatically removed on shut down.
-
Instead of "To do..." how about something like, "This is my new Dashboard page for Review Board!" That way, it makes it more clear what we're showing, and looks less like we forgot to put something in the documentation.
SL
- Change Summary:
-
Fixed various issues as per Christian and Mike's comments.
- Diff:
-
Revision 2 (+148 -1)
-
-
They don't use them as a primary mechanism, they *are* a primary mechanism. I'd be OK with "Extensions can use "hooks" as a mechanism for customizing Review Board's appearance and behavior." Also, make sure to use "Review Board". Not ReviewBoard or Reviewboard.
-
Let's say this: Notice how sample_extension.urls was included in the patterns. In this case, sample_extension is the package name for the extension, and urls is the module that contains the patterns.
-
-
-
