Mock test CLI and complete docstrings

[vladimir-v-diaz]

Description of issue or feature request:

The CLI and supporting were reviewed in #741, but repo.py still needs mock tests and docstrings.

[michizhou]

Hi @vladimir-v-diaz, if it's alright with you, I would be glad to take a look at resolving this issue! Just let me know what types of mock tests and docstrings you would like me to include or edit in repo.py.

[alyptik]

@michizhou That's very alright! Unfortunately, I'm not completely sure on what type of docstrings/mock tests were meant, so I'll let @vladimir-v-diaz clarify what should be edited/included.

[JustinCappos]

@sebastien Awwad <gsa215@nyu.edu> may be a better person to ask. Sebastien?

…

On Tue, Oct 9, 2018 at 10:35 PM Joey Pabalinas (jp) < ***@***.***> wrote: @michizhou <https://github.com/michizhou> That's very alright! Unfortunately, I'm not completely sure on what type of docstrings/mock tests were meant, so I'll let @vladimir-v-diaz <https://github.com/vladimir-v-diaz> clarify what should be edited/included. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#763 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA0XD3tTVn5Tad-zVcFdKy8uJzaG-Gfqks5ujV0FgaJpZM4U8H2m> .

[awwad]

I'd hazard that what is meant here is two things:

• While there is documentation for the CLI (general doc; more CLI examples), there is some need for more explanation of the arguments and/or more examples of use in in the docstrings of the CLI scripts.
  • repo.py has examples in the docstring, but the command-line arguments themselves are not listed and individually explained. That should probably be done, or if parse_arguments() seems conveniently readable enough (probably not), the docstring of the module should point to it.
  • The same goes for client.py, but it could probably use a few more examples in addition to the explanation of command line arguments.
• Vlad may have been suggesting doctest, which would need to be used differently for these CLI modules than it is for other modules. I don't know if this would be helpful for the CLI modules. Currently, doctest is used for repository_lib.py, repository_tool.py, developer_tool.py, and formats.py. It is seemingly not linked to our continuous integration testing, though. I think that's a project for another issue, so I'd focus on the first bullet here instead.

[awwad]

He could also have meant the addition of testing via something like the usual unittest scheme that TUF uses (see all the tests in tests/) to test the CLI scripts. This is a larger and more important task.

Either would be helpful. Please let me know which you'd rather work on and I'll give you more instruction as necessary.

[michizhou]

@awwad I would like to get started with the documentation part of it. Once that is taken care of, I would be glad to help add additional testing for the CLI scripts and possibly look into the use of doctest. Let me know if that works for you. Thanks!

[michizhou]

@awwad Just wanted to follow up with you on working with the documentation of the CLI script docstrings. I would appreciate it if you could give me more instruction and guidance on getting started.

[awwad]

Sorry, I didn't realize you were waiting for more. The two checklist items in the first bullet of the comment above were what I had in mind for the documentation bit.

It might be hard for me to tell what introduction is necessary, so questions would be very helpful. 😃

If you need to get a feel for what's going on, I'd try out the command line tool, following these tutorials until you feel confident.

[michizhou]

@awwad I have just pushed a new PR that addresses the concerns over documentation in the CLI test scripts (i.e. repo.py and client.py) with new command-line descriptions and examples added. Let me know if you need me to make any additional changes. Thanks!

[michizhou]

@awwad Just wanted to follow up with you again since I did create a PR that addresses this issue over a week ago. I would appreciate it if you could look it over and review it. Thanks!

[awwad]

#796 merged. Thanks, @michizhou!

repo.py still needs docstrings for a number of its functions before I can close this.

[michizhou]

@awwad Not a problem! Just wanted to let you know that I recently opened a new PR that should help definitely resolve this issue, as I have provided docstrings for all functions that don't have one already.