API examples & expanded documentation

[Yenthe666]

Operating system

Ubuntu 18.04.1

nbgrader --version

0.5.5

jupyterhub --version (if used with JupyterHub)

No hub.

jupyter notebook --version

5.7.8

Expected behavior

API samples / code / information in the documentation.

Actual behavior

At this point there is very limited information about the API. It took me a while to find a minor example at https://nbgrader.readthedocs.io/en/stable/user_guide/advanced.html which was hidden very well. It would be great to have an example for every class instance in nbgrader (Notebook, Assignment, BaseCell, GradeCell, SolutionCell, TaskCell, SourceCell, Student, SubmittedAssignment, SubmittedNotebook, Grade, Comment, Course and Gradebook). I'd propose a new main section in the documentation just like User Documentation and Configuration but then for API with a submenu for every class in nbgrader.

If you'd like I'm happy to start some docs with examples I guess. 😄

[jhamrick]

Is https://nbgrader.readthedocs.io/en/stable/api/index.html close to what you're looking for?

I agree it would be nice to have some more worked examples of using the API/Gradebook, though. Perhaps in that page I linked to we could create a new page called "Examples" and then have a variety of examples, like the one that you linked to as well as some other useful receipes.

On Sun, Jun 30, 2019 at 4:24 PM Yenthe V.G notifications@github.com wrote:

Operating system

Ubuntu 18.04.1 nbgrader --version

0.5.5 jupyterhub --version (if used with JupyterHub)

No hub. jupyter notebook --version

5.7.8 Expected behavior

API samples / code / information in the documentation. Actual behavior

At this point there is very limited information about the API. It took me a while to find a minor example at https://nbgrader.readthedocs.io/en/stable/user_guide/advanced.html which was hidden very well. It would be great to have an example for every class instance in nbgrader (Notebook, Assignment, BaseCell, GradeCell, SolutionCell, TaskCell, SourceCell, Student, SubmittedAssignment, SubmittedNotebook, Grade, Comment, Course and Gradebook). I'd propose a new main section in the documentation just like User Documentation and Configuration but then for API with a submenu for every class in nbgrader.

If you'd like I'm happy to start some docs with examples I guess. 😄

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/jupyter/nbgrader/issues/1162?email_source=notifications&email_token=AAAUL5DZBOGW6UD22WWLHLTP5DF2ZA5CNFSM4H4MZWL2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4G4P5MKA, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAUL5FLWWXBMI3H5JU4RBTP5DF2ZANCNFSM4H4MZWLQ .

[Yenthe666]

Thanks for the quick feedback! It just misses some examples that you can copy and get you quickly going in no time. It could be either an example under any class in your link or a new page with an example per class. Both would be a big benefit for starting developers I believe.

[jhamrick]

Could you provide an example or two of what you would envision this looking like?

I am just not sure what that would look like exactly to have one example per class, since most of the classes are not things that are meant to be used directly---you should generally only be interfacing with the database through the Gradebook object. Maybe the way to do this would be to have recipes that look like the following:

1. Create the gradebook.
2. Query an object using the gradebook (e.g. lookup a student).
3. Demonstrate accessing some of the attributes on that object (e.g. first_name).

On Sun, Jun 30, 2019 at 5:16 PM Yenthe V.G notifications@github.com wrote:

Thanks for the quick feedback! It just misses some examples that you can copy and get you quickly going in no time. It could be either an example under any class in your link or a new page with an example per class. Both would be a big benefit for starting developers I believe.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/jupyter/nbgrader/issues/1162?email_source=notifications&email_token=AAAUL5BYYBPNNZHPY5CXTYLP5DL6DA5CNFSM4H4MZWL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODY4PGCA#issuecomment-507048712, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAUL5C6G32HIJIC7FTMKZTP5DL6DANCNFSM4H4MZWLQ .

[Yenthe666]

@jhamrick sure thing. For example to create a gradebook and view gradebooks:

import pandas as pd
from nbgrader.api import Gradebook

# Create a database connection
with Gradebook('sqlite:///gradebook.db') as gb:
    # Create an assignment from the Gradebook class if doesn't exist yet
    try:
        gb.add_assignment('course101')
    except Exception as error:
        print('error creating course: ' + str(error))

    # List assignments for the gradebook
    assignments = gb.assignments
    # Every assignment in gb.assignments is an Assignment record. All values for this record
    # can be accessed through the field names.
    for assignment in assignments:
        print('assignment: ' + str(assignment.name))