Add missing docstrings to `node` module

sajith commented 4 months ago

Addresses #318. Adds some docstrings to fablib.node.Node methods.

I'm not familiar with the usage of Node.generate_template_context(), Node.get_template_context(), and Node.render_template(), so leaving that out for a later round.

Also re-formats docstrings in fablib and slice modules so that tox -e docs will work. Tox docs environment is set up to treat warnings as errors.

coveralls commented 4 months ago

Pull Request Test Coverage Report for Build 9764087934

Details

1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
6 unchanged lines in 1 file lost coverage.
Overall coverage increased (+0.01%) to 18.309%

Files with Coverage Reduction	New Missed Lines	%
fabrictestbed_extensions/fablib/node.py	6	7.84%
<!--	Total:	6		-->

Totals
Change from base Build 9646708720:	0.01%
Covered Lines:	1166
Relevant Lines:	4704

💛 - Coveralls

sajith commented 4 months ago

I made a table of fabrictestbed.fablib.node.Node methods that do not have a docstring. I strongly suspect that many of them could be (or should be) private.

delete() is the one that did not have a docstring.
It doesn't seem that we have any usage examples of set_user_data() and get_user_data() in notebook examples. If these are meant to be public, they deserve better documentation.
Unsure about many others.

The ticked boxes mean that I've tried to add something (mostly a warning) to the method next to it in this PR.

method	comment	should be made private?
- [X] `get_fablib_manager()`	Called internally many times	maybe?
- [X] `get_pretty_name_dict()`	Called by `show()`	maybe?
- [ ] `generate_template_context()`	What is this used for?
- [ ] `get_template_context()`	Called by `render_template()`	maybe?
- [ ] `render_template()`	Called by `get_ssh_command()` and `run_post_boot_tasks()`	maybe?
- [X] `get_networks()`	Called by `list_networks()`	maybe?
- [X] `get_paramiko_key()`	Called by `execute()`,`upload_file()`, and `download_file()`	yes
- [ ] `get_fim()`	Shortcut to `get_fim_node()`. Do we need both?	yes
- [ ] `set_user_data()`	No examples in notebooks
- [ ] `get_user_data()`	No examples in notebooks
- [X] `delete()`	Added rudimentary docstring
- [X] `init_fablib_data()`	Called by `new_node()`	yes
- [X] `get_fablib_data()`	Called internally many times	yes
- [X] `set_fablib_data()`	Called internally many times	yes
- [X] `get_routes()`	Called by `config_routes()` which is called by `config()`	no?
- [X] `config_routes()`	See above.	maybe?
- [X] `run_post_boot_tasks()`	Called by `config()`	maybe?
- [X] `run_post_update_commands()`	Called by `config()`	maybe?
- [X] `is_instantiated()`	Called by `config()`	maybe?
- [X] `set_instantiated()`	Called by `config()`	maybe?
- [X] `run_update_commands()`	Called by `config()`	maybe?
- [ ] `set_run_update_commands()`	What is this used for? No usage in notebooks.

fabric-testbed / fabrictestbed-extensions