Add in better, more up to date, examples

[seemethere]

Overview

The included examples are out of date and not useful anymore we need to add examples for:

• [ ] Using the base functionality with pandas
• [ ] Using the base functionality with pandas
• [ ] Base example with how to access player stats
• [ ] Base example with how to access game stats

[murrayLuke]

I would be willing to write these for you if you give me a list of what you would like the examples to do. I can either write the whole thing in markdown or give you a jupyter notebook of them.

[seemethere]

I think a jupyter notebook would be excellent 😄 @murrayLuke

[murrayLuke]

ok i will send you a draft by december 22. If you can clarify with exactly what calls you want me to show that might make it better, but if not I'm sure I can come up with something. @seemethere

[murrayLuke]

In a follow up to these does anybody know what the following parameters for boxscore are used for, or what valid inputs to them would be

• StartPeriod
• EndPeriod
• StartRange
• EndRange
• RangeType

[bttmly]

StartPeriod and EndPeriod are for looking at things like box scores. They tell which "periods" (i.e. quarters, plus overtime) you're interested in getting data for. The range seems to be [0..10] where 0 means all periods, then [1..4] representing the four quarters of regulation and [5..10] representing up to six overtime periods. No idea about StartRange, EndRange, and RangeType – I've only seen all three as 0.

[murrayLuke]

@nickb1080 thanks appreciate it

[bttmly]

FWIW, you may find this JSON representation useful – there may be some naming inconsistencies between it and this repo, but it's pretty close. I use it to generate (shitty, currently) docs.

[murrayLuke]

yea thats awesome I'm currently just trying to think about the best way of approaching this documentation. trying to strike a balance between it being overly verbose and explaining too many things, or not explaining enough things. Also there are quite a few functions and parameters to cover so creating a wiki/utilizing the current one would probably be best. As I get into this I begin to see that jupyter may not be the best approach except for when specifically talking about pandas integration

[murrayLuke]

Today I started porting the in project comments to googles python comment style. This lets us use the napoleon extension for sphinx documentation to auto generate documents with well formatted parameters and more. I've attached an example of the nba_py page with parameters labeled for the scoreboard object, as well as the BASEURL etc. The documentation by default does not include private parameters and methods such as those beginning with an '_'.

Let me know what you think. The reason I took this approach is because jupyter is probably best for code examples, but the actual parameters are better documented in this format.

The example can be seen in the nba_py.html file zipped within here so that it contains all necessary css, js, etc. @seemethere check out the nba_py.html file within the zipped folder below

html.zip

Right now the data is generated semi programmatically, it could be generated completely programmatically using a separate json structure to store function names with their associated summaries and descriptions. The greatest risk with this is making sure bit rot doesn't set in, for instance if function names, parameters, or return values change.

[murrayLuke]

here's a programmatically generated map of all the functions which generate pandas dataframes. json.

The json is organized as follows.

At the top level are classes. Each class has a parameters and methods.

Each parameter has the following { "valid": "", "name": "game_id", "short_summary": "TODO INSERT SUMMARY", "default": "", "type": "TODO INSERT TYPE", "long_description": "" }

• valid will be used to store a valid example of the parameter. For instance. day could be the integer 3.
• name is the name given to the parameter when passed into a python function.
• short summary is used to give a short summary of what the parameter does
• type is the type of the parameter in python for instance a string would be 'str'
• long description is an optional argument to give a long description of the parameter

I believe many of the parameters seen in nba_py repeat from class to class, so these could be filled out in large batches greatly reducing the amount of work. An interesting consequence of using these, is that they could be used to programmatically generate tests of all the classes, where valid parameters are input, and the success of all the classes methods are tested.

Each method has the following

{ "columns": {}, "long_description": "", "short_summary": "TODO INSERT SUMMARY", "name": "overall" }

Where columns is a list of column values returned by the pandas dataframe object. long description is an optional long description of what the method does. short summary is a short summary of what the method does, and name is the name of the method.

possible improvements

filling in short summaries for functions and parameters from current docstrings

Let me know if you think this would be useful. @nickb1080 let me know if you find this interesting.

[murrayLuke]

I've programmatically created a list of parameters to all the functions. This could be used to generate up to date and uniform documentation across the entire project. If anyone wants to clone the gist and fill in anything they know, that would be great, and explanation of what the fields are is provided in the previous comment.

the gist

[hold-the-phone]

Hey @seemethere, loving the project! I could really use some functional examples though when you get a minute. Thanks for all the work.