Fixup the simple plugin setup docs.

Review Request #4241 — Created Sept. 16, 2016 and submitted

jsirois
pants
jsirois/issues/3877
3877, 3878
b436852...
pants-reviews
patricklaw, peiyu, zundel
src/docs/howto_plugin.md | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)
Rendered here:
  http://pantsbuild.github.io/staging/jsirois/issues/3877/howto_plugin.html

CI went green here:
  https://travis-ci.org/pantsbuild/pants/builds/160488897
  • 0
  • 0
  • 0
  • 1
  • 1
Description From Last Updated
JS
MA
  1. Thanks, John. Mostly take-it-or-leave it comments below.

  2. src/docs/howto_plugin.md (Diff revision 1)
     
     

    So, at one point I heard that plugin __init__.py should be non-empty. Perhaps that is only for the internal pants plugins and has just been cargo culted everywhere.

    Ours say:

    __import__('pkg_resources').declare_namespace(__name__)

    It wouldn't surprise me to find out that it isn't required - I have never noticed an adverse effect when it wasn't included.

    1. A namespace package is required only if its required ;). This is only needed if you know or guess that the same python package (prefix) may be declared elsewhere so that the importer can merge packages successfully. If you own the namespace, there is no need. Granted, hadoop in this case is a pretty generic name and there very well could be some other pants code in-play that uses - say - a 3rdparty hadoop library that also uses, say hadoop.mapreduce and hadoop.namenode packages and then this would be a problematic example.

  3. src/docs/howto_plugin.md (Diff revision 1)
     
     

    white space at EOL here

  4. src/docs/howto_plugin.md (Diff revision 1)
     
     

    The details do not match the instructions here ("up to but not including the root directory") since there is no plugins/__init__.py file shown.

    1. It does match, since the root directory (aka source root, aka PYTHONPATH prefix) of the python package is plugins/, so up-to but not including means plugins/hadoop/__init__.py is the 1st package (ie: hadoop is a package and '' is not).
      That said, the wording is tripping up experienced python / pants people so that's not good. I'm open to concrete alternative wording.

  5. src/docs/howto_plugin.md (Diff revision 1)
     
     

    I think I would remove the "When registering a backend in pants.ini" part of this paragraph. The pants.ini is discussed more in the next section.

  6. src/docs/howto_plugin.md (Diff revision 1)
     
     

    It might be worth mentioning that pythonpath + the plugin's backend_packages entry should represent the path to the register.py. If you can think of a simple way to explain that.

    I used to get confusing registration errors until I finally understood that relationship.

    1. Yup - makes sense, a nice simple rule to apply to the finished product.  Added.
  7. 
      
JS
MA
  1. 
      
  2. 
      
JS
Review request changed

Status: Closed (submitted)

Change Summary:

Now on master:

git log -1 origin/master
commit 392c92c985cbc4c1eac8ef8da736c61b7ce4e89f
Author: John Sirois <john.sirois@gmail.com>
Date:   Sun Sep 18 15:09:02 2016 -0600

    Fixup the simple plugin setup docs.
    
    Testing Done:
    Rendered here:
      http://pantsbuild.github.io/staging/jsirois/issues/3877/howto_plugin.html
    
    CI went green here:
      https://travis-ci.org/pantsbuild/pants/builds/160488897
    
    Bugs closed: 3877, 3878
    
    Reviewed at https://rbcommons.com/s/twitter/r/4241/
ST
  1. Ship It!
  2. 
      
Loading...