Fixup `PythonTarget` `resource_targets` docs.

Review Request #4148 — Created Aug. 10, 2016 and submitted

jsirois
pants
jsirois/resource_targets/doc
3771
397010c...
pants-reviews
benjyw, patricklaw
This also fixes the `resources` target docs to be language neutral.

 src/python/pants/backend/python/targets/python_target.py | 11 ++++++++---
 src/python/pants/build_graph/resources.py                |  9 ++++-----
 2 files changed, 12 insertions(+), 8 deletions(-)
The BUILD dictionary is rendered here:
  http://pantsbuild.github.io/staging/jsirois/resource_targets/doc/build_dictionary.html

CI went green here:
  https://travis-ci.org/pantsbuild/pants/builds/151260312
  • 0
  • 0
  • 0
  • 2
  • 2
Description From Last Updated
JS
  1. This is a minimal fix in the existing styles.  Much more fixing could be done on target parameter docstrings, but I'm going for a surgical strike here.
  2. 
      
ST
  1. 
      
  2. At least in java land, paths are relative to the nearest source_root... they're only relative to the BUILD file if there isn't a source_root.

    Since the synthetic resources target is created right next to the existing target, I think it should get the same source root... but I might be misunderstanding.

    1. I used existing param doc language for sources and it seems correct to me if read as the BUILD author. Inside src/python/a/b/BUILD I write (re)sources=['c/file'] to capture src/python/a/b/c/file. I do not write (re)sources=['a/b/c/file'] (the source root relative path).

    2. Ah, gotcha. This is referring to how the resources are declared, rather than how they are used.

  3. 
      
JS
WI
  1. 
      
    1. List is not the type here, list is. IOW, the typical doc rule of :param list things: This is a proper sentence description of things with 1st word capped and period. does not apply for the 2nd entry in the 2 entry :param... form or the 2 entry :returns:..., :rtype:... form.

  2. 
      
LE
  1. 
      
  2. The next sentence mentions Python and Java. This one does not. Either put in both as well or kick the entire sentence out.

    1. The sentence was added to head off a very common confusion; it seems to me it pulls enough weight to break perfect symmetry.
    2. To be more clear, it addresses a common jvm-only problem. There is no bundle support for python today.
  3. 
      
ST
  1. Ship It!
  2. 
      
JS
Review request changed

Status: Closed (submitted)

Change Summary:

Now on master:

git log -1 origin/master
commit 76d5ae7edb9efcbc57a3260f010f4608683b8fd0
Author: John Sirois <john.sirois@gmail.com>
Date:   Mon Aug 29 09:53:06 2016 -0600

    Fixup `PythonTarget` `resource_targets` docs.
    
    This also fixes the `resources` target docs to be language neutral.
    
    Testing Done:
    The BUILD dictionary is rendered here:
      http://pantsbuild.github.io/staging/jsirois/resource_targets/doc/build_dictionary.html
    
    CI went green here:
      https://travis-ci.org/pantsbuild/pants/builds/151260312
    
    Bugs closed: 3771
    
    Reviewed at https://rbcommons.com/s/twitter/r/4148/
Loading...