don't insist on @manual.builddict; rm it from many places

Review Request #703 — Created July 19, 2014 and submitted

lahosken
pants
pants-reviews
jsirois
@manual.builddict is mostly redundant now. So clean clean clean.

Change the BUILD-Dictionary-building logic: document registered things; not just those registered things that were tagged @manual.builddict.

This change adds/removes some things from the BUILD dictionary:

Removes:
  __file__
  ROOT_DIR

Adds:
  buildfile_path
  config
  get_buildroot
  get_scm
  pants_version
  set_scm
  zglobs

Added some docstrings.
Changed some lambda to lambda+__doc__

Motivation:

A couple of refactorings ago, we had lots of symbols def'd in BUILD files we didn't want folks to use. "Yeah, you _could_ use JvmTarget for that, but please use java_library instead." We used @manual.builddict to carefully mark those things we wanted to show up in the BUILD Dictionary.

In these enlightened days, we carefully craft our register.py files to specify the symbols we want. Thus, @manual.builddict is mostly a duplication of effort. (It's still useful for methods: most methods shouldn't be used in BUILD files. But a few of them are still around. So, even with this change, we mark those with @manual.builddict)
https://travis-ci.org/pantsbuild/pants/builds/30317126

publish_docs.sh and eyeballing
LA
LA
JS
  1. Excellent.
    1. PTAL. The easy stuff is done, yay. The not-so-easy stuff, is... uhm, yeah.
  2. These are now registered as exposed_objects each and every one - except for java_tests maybe in which case its invalid.  A todo to move these to pydoc if this is correct would be good.
  3. You may not have a story for true 3rdparty plugins yet, but it would be good to note that in a TODO/issue.  There should be no hardcoded list here.
    1. (Careful, this code moved ( https://rbcommons.com/s/twitter/r/703/diff/?page=1#chunk17.42 ) and changed; but there's still a hardcoded list.)
      
      Yeah, the hardcoded list is pretty sloppy. Given the choice of
      
      (a) rigorously figuring out which BUILD file thingies are Python, JVM, etc, or
      
      (b) giving up the somewhat-handy JVM and Python lists at the top of http://pantsbuild.github.io/build_dictionary.html
      
      ...I suspect we'd give them up.
      
      Depending on how much you dislike the hardcoded lists, maybe we should give up the somewhat-handy JVM and Python lists now?
  4. This pydoc is good with the end """ on a line by itself - above and below do it different.
  5. This is what @functools.wraps is for - but it may not work on lambdas.  Actually it should - give it a shot.
    1. I'm not smart enough to figure this out on a plane, but I think I lied.  Suffice it to say it would be nice to make doc transfer a bit easier for folks doing simple currying of the context.
    2. The lambda loses the __doc__. I tried sweeping this under the rug by making a helper function. But I dunno if that actually makes things clearer. And I was bluffing when I said "Bind" in the docstring; I learned my functional programming on the streets and often misuse terms.
      
      helper function in src/python/pants/base/build_file_aliases.py:
      https://rbcommons.com/s/twitter/r/703/diff/?page=3#47
  6. src/python/pants/base/build_manual.py (Diff revision 2)
     
     
    tags is now unused, kill
  7. 
      
LA
JS
  1. 
      
  2. Maybe curry_context(...)
  3. 
      
LA
JS
  1. Ship It!
  2. 
      
LA
Review request changed

Status: Closed (submitted)

Loading...