Documentation of the extension system

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

smacleod
Review Board
reviewboard
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)
     
     
     
    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)
     
     
     
    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)
     
     
    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)
     
     
    "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)
     
     
    easy to use -> easy-to-use
  4. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    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)
     
     
    is created?  I think we mean "should be created".
  6. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    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)
     
     
    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)
     
     
    - 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)
     
     
    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)
     
     
    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)
     
     
     
    Two blank lines before each section.
  3. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Should have a space before the <..> in links. Same for all others.
  4. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    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)
     
     
     
     
    Two blank lines.
  6. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
    1. this was swapped with the previous line accidentally. Fixed.
  7. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    One blank line between each of these. Same for others in the class.
  8. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  9. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    When referencing filenames or directories, use :file:`..`
  10. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  11. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    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
  12. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    I'd say just nuke this if we don't have content yet.
  13. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    No blank line.
  14. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  15. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Wrapping is funky here.
  16. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  17. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    :guilabel:`Configure`
  18. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    :file:`admin_urls.py`
  19. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  20. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    We should link to it.
  21. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Should be capitalized. Here and the next entry. Also, only one space.
  22. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Use `` for the module name.
  23. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  24. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Alignment is wrong.
  25. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    :guilabel:`Database`
  26. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
  27. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
    Link to it.
  28. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  29. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  30. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Alignment is wrong.
  31. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  32. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  33. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    Only one blank line needed.
  34. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  35. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
    Two blank lines.
  36. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    We should be linking to the docs instead of just listing the module. Same at other places.
  37. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
    Same here about linking.
  38. docs/codebase/extending/extensions.txt (Diff revision 3)
     
     
     
     
     
    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.)
  39. 
      
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: Closed (submitted)

Change Summary:

Committed to master as df930359
Loading...