Documentation of the extension system

Review Request #2950 — Created March 10, 2012 and submitted

Information

Review Board

Reviewers

This is the start of documentation for the extension system. I have focused on documenting the status for version 1.7+.
Repeatedly rendered as html while writing. Quick proofreading done.
Description From Last Updated

I wonder if mentioning Extension Hooks by name this early is more confusing than useful. Maybe something more like: "Review …

mike_conleymike_conley

When you say "conventions", it reminds me - we should mention that we've designed the framework to follow many of …

mike_conleymike_conley

We should mention that when an extension is disabled, tables for models are not dropped. The user would have to …

mike_conleymike_conley

Two blank lines before each section.

chipx86chipx86

"an" Extension. And I'm not sure we need to capitalize Extension everywhere, unless we're referring specifically to the Extension class...

mike_conleymike_conley

I think there should be a comma after minimum.

AM ammok

Should have a space before the <..> in links. Same for all others.

chipx86chipx86

Might be nice to do "" instead of "sample_extension". Or put it in italics, actually, since that's how the the …

chipx86chipx86

Two blank lines.

chipx86chipx86

Two blank lines.

chipx86chipx86

- Seems like this line was swapped with the next. - Add a comma between 'information' and 'see'

AM ammok

"For" ?

chipx86chipx86

One blank line between each of these. Same for others in the class.

chipx86chipx86

easy to use -> easy-to-use

mike_conleymike_conley

Two blank lines.

chipx86chipx86

Another thing we could mention, is that evolve is also run programmatically. That way, an extension's models can change over …

mike_conleymike_conley

When referencing filenames or directories, use :file:`..`

chipx86chipx86

Two blank lines.

chipx86chipx86

This is fine for development installs, but people developing against a Review Board install are likely to use rb-site. In …

chipx86chipx86

I'd say just nuke this if we don't have content yet.

chipx86chipx86

For some documentation on template hooks see: http://code.google.com/p/reviewboard/wiki/Building_Extensions#Adding_a_Template_Hook

CI cim1

No blank line.

chipx86chipx86

Two blank lines.

chipx86chipx86

Wrapping is funky here.

chipx86chipx86

Two blank lines.

chipx86chipx86

:guilabel:`Configure`

chipx86chipx86

is created? I think we mean "should be created".

mike_conleymike_conley

:file:`admin_urls.py`

chipx86chipx86

:file:

chipx86chipx86

Two blank lines.

chipx86chipx86

We should link to it.

chipx86chipx86

Should be capitalized. Here and the next entry. Also, only one space.

chipx86chipx86

Use `` for the module name.

chipx86chipx86

Two blank lines.

chipx86chipx86

Alignment is wrong.

chipx86chipx86

:guilabel:`Database`

chipx86chipx86

extensions => extension's

AM ammok

:file:

chipx86chipx86

Link to it.

chipx86chipx86

Two blank lines.

chipx86chipx86

:file:

chipx86chipx86

Two blank lines.

chipx86chipx86

Alignment is wrong.

chipx86chipx86

:file:

chipx86chipx86

Two blank lines.

chipx86chipx86

Two blank lines.

chipx86chipx86

Only one blank line needed.

chipx86chipx86

Two blank lines.

chipx86chipx86

This is only one part of the puzzle - install_requires will ensure that certain packages are installed in order to …

mike_conleymike_conley

:file:

chipx86chipx86

Two blank lines.

chipx86chipx86

We should be linking to the docs instead of just listing the module. Same at other places.

chipx86chipx86

:file:

chipx86chipx86

Same here about linking.

chipx86chipx86

We should mention that this is part of the Review Board tree, and will require a checkout. (Really, we should …

chipx86chipx86
mike_conley
  1. Steven:
    
    Looks like you've covered all of the bases so far.  Just a few minor, high-level suggestions below.
    
    -Mike
  2. docs/codebase/extending/extensions.txt (Diff revision 1)
     
     
     
    Show all issues
    I wonder if mentioning Extension Hooks by name this early is more confusing than useful.
    
    Maybe something more like:
    
    "Review Board's functionality can be enhanced by installing a Review Board Extension.  Writing and installing an Extension is an excellent way to tailor Review Board for your exact needs."
    1. Switching to start off less technical.
  3. docs/codebase/extending/extensions.txt (Diff revision 1)
     
     
     
    Show all issues
    When you say "conventions", it reminds me - we should mention that we've designed the framework to follow many of Django's conventions.
  4. docs/codebase/extending/extensions.txt (Diff revision 1)
     
     
    Show all issues
    We should mention that when an extension is disabled, tables for models are not dropped.  The user would have to use
    
    ./reviewboard/manage.py evolve --purge
    
    In order to generate evolutions to drop those tables.
    1. Good point. Added.
  5. 
      
SM
SM
mike_conley
  1. Continues to look good.
  2. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    "an" Extension.
    
    And I'm not sure we need to capitalize Extension everywhere, unless we're referring specifically to the Extension class...
    1. I was unsure about this when first writing the document. I felt like Review Board Extension or Extension, was the name for these extensions to Review Board, so I was capitalizing. It is confusing since the class is also name Extension. I've switched it over to lower case when not referring to the class, thanks.
  3. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    easy to use -> easy-to-use
  4. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    Another thing we could mention, is that evolve is also run programmatically.  That way, an extension's models can change over time.  The developer just needs to update their model definitions...I don't think they need to enable/disable the extension to trigger the evolve, but you should double-check.
    1. Is the evolution run with --hint --evolve, or are they explicit evolutions the extension needs to provide? I guess I'll have to look in to this section with a little more depth.
  5. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    is created?  I think we mean "should be created".
  6. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    This is only one part of the puzzle - install_requires will ensure that certain packages are installed in order to make the extension install successful - but it doesn't describe how we can have extensions be dependent on one another.
    
    A "requirements" list can be declared in the Extension class that gives the names of extensions that must be enabled in order for this extension to be enabled.
    1. Thanks for reminding me, I'd completely forgotten about the requirements lists!
  7. 
      
AM
  1. I just had a few nitpicks to make.
    1. Thanks, lots of good stuff here. Don't be afraid to make issues on the stuff you want changed, it helps me keep track of work, and we can always drop it if we need to.
  2. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    I think there should be a comma after minimum.
  3. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    We should probably be consistent in capitalizing Python (here and below).
    1. Good catch, thanks.
  4. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Either use a lower case Extension or change it to subclass.
  5. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    comma between 'information' and 'see'.
  6. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    - Seems like this line was swapped with the next.
    - Add a comma between 'information' and 'see'
    1. Strange, must have accidentally dragged it or something. :P
  7. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    in to => into?
    1. Oh English grammar, and your complexities! Good catch!
  8. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    in depth => in-depth
  9. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    extensions => extension's
  10. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    auto detection => auto-detection
  11. 
      
CI
  1. 
      
  2. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    For some documentation on template hooks see: http://code.google.com/p/reviewboard/wiki/Building_Extensions#Adding_a_Template_Hook
  3. 
      
chipx86
  1. The docs look great in general. You're going to see the same few comments from me listed a dozen times each. Just some stylistic stuff, and we should also be better at linking to external docs when we talk about them.
  2. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    Two blank lines before each section.
  3. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    Should have a space before the <..> in links. Same for all others.
  4. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    Might be nice to do "<extensiondir>" instead of "sample_extension". Or put it in italics, actually, since that's how the the docs typically indicate something that's to be replaced.
  5. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  6. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  7. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    "For" ?
    1. this was swapped with the previous line accidentally. Fixed.
  8. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    One blank line between each of these. Same for others in the class.
  9. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  10. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    When referencing filenames or directories, use :file:`..`
  11. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  12. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    This is fine for development installs, but people developing against a Review Board install are likely to use rb-site. In that case:
    
        rb-site manage /path/to/site evolve -- --purge
  13. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    I'd say just nuke this if we don't have content yet.
  14. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    No blank line.
  15. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  16. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    Wrapping is funky here.
  17. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  18. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :guilabel:`Configure`
  19. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:`admin_urls.py`
  20. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:
  21. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  22. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    We should link to it.
  23. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    Should be capitalized. Here and the next entry. Also, only one space.
  24. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    Use `` for the module name.
  25. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  26. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Alignment is wrong.
  27. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :guilabel:`Database`
  28. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    :file:
  29. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Show all issues
    Link to it.
  30. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  31. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:
  32. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  33. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    Alignment is wrong.
  34. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:
  35. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  36. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  37. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    Only one blank line needed.
  38. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  39. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:
  40. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Show all issues
    Two blank lines.
  41. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    We should be linking to the docs instead of just listing the module. Same at other places.
  42. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    :file:
  43. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Show all issues
    Same here about linking.
  44. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Show all issues
    We should mention that this is part of the Review Board tree, and will require a checkout.
    
    (Really, we should turn this generator into a management command, or otherwise make it available externally.)
  45. 
      
SM
SM
SM
mike_conley
  1. As discussed in IRC, this is a great start, and we can add more stuff as we go along.  Thanks Steven!
  2. 
      
SM
Review request changed
Status:
Completed
Change Summary:
Committed to master as df930359