docs: adds docstrings (refactor: rename local parameter)

[consideRatio]

This PR combines pure documentation commits with a refactoring commit that merits more closer review.

I'm not 100% it's non-breaking for all users to rename nbapp to app in the settings. To my knowledge, we only set it to be able to read it from this code base. For reference, setting nbapp in settings was introduced in #75.

[consideRatio]

This is the change of importance. Will something rely on the nbapp setting besides the one reference we have when we call it in handlers.py like this?

gp = GitPuller(repo, repo_dir, branch=branch, depth=depth, parent=self.settings['app'])

[yuvipanda]

Ah, so this changes web_app.settings globally for all installed plugins, which I think is a mistake originally. I think we should just not touch web_app.settings at all, and use the initialize method in the tornado handler instead. The third item in the tuple passed to add_handlers can contain arbitrary dict that is passed as kwargs to an initialize method if found. Let's use that and stop putting things in the global settings?

[consideRatio]

Ah! I went for adding a # FIXME note and force pushed to avoid making a reverting commit that can cause an unessecary merge conflict for Sean's plugin PR.

I opened #248 to represent this!

I think this PR is now safe to merge without any risk of complications.

[manics]

Kinda of related, there's an undocumented environment variable NBGITPULLER_APP

nbgitpuller/nbgitpuller/handlers.py

Line 149 in fdd54bd

app_env = os.getenv('NBGITPULLER_APP', default='notebook')

Do you know it's significance?

[consideRatio]

EDIT: Let's not discuss this here, I opened an issue #247 about it

@manics it seem to have been added by me four years ago in #41 😮

I did some git history inspection:

• Ability to launch into JupyterLab #41 added NBGITPULLER_APP, a default value for an app parameter accepting notebook and lab.
• Documentation about it updated in Update README.md #48
• Documentation on constructing the url removed in favor of using a link generator in Add new link generator instructions #62

Overall, it seems that it does the single thing of "if set to lab", the web handler for /git-pull endpoint will default to prepending /lab/tree to a post git-pull redirection path. It won't affect gitpuller the CLI though.

I conclude that the https://jupyterhub.github.io/nbgitpuller/link only crafts links using urlpath directly though, and the NBGITPULLER_APP is a default value for a app query parameter, which only has an influence if urlpath isn't set.

I'd love to see this env var and the entire app query parameter removed to reduce complexity, but breaking existing links isn't fun. @yuvipanda do you have a suggestion with regards to something to do with the logic about having an app parameter and/or the NBGITPULLER_APP env which is the app parameters default value?

[yuvipanda]

Thanks a lot for this, @consideRatio!