Format docs

[Cjkjvfnby]

Describe your change:

Fix some warnings that would be raised by adding adding flake8-docstrings to the pre-commit hooks.

This PR is just to show the features of that tool.

There are two groups of checks.

Documentation

This looks like a good match with the repo guidelines. For classes and functions, there is an easy trick to use the leading underscore for names, then classes/functions won't be public, so you could document only what you need.

• D100 Missing docstring in public module
• D101 Missing docstring in public class
• D104 Missing docstring in public package

Docstring formating

It might be a bit confusing for people since the summary does not have a lot of sense in the context of this repo. It will have the same words as in the file and function names and algorithm description is in the module docstring. Ignoring that line is not an option since there is a lot of code with doctests.

• D205 1 blank line required between summary line and description
• D400 First line should end with a period
• D401 First line should be in imperative mood; try rephrasing
• D403 First word of the first line should be properly capitalized

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Documentation change?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
• If this pull request resolves one or more open issues then the commit message contains Fixes: #{$ISSUE_NO}.

[CaedenPH]

Perhaps what you could normalize would be all the different types of docstring params/returns, ie

"""
:param a: The first integer
:param b: The second integer
:return: The output
"""

and

"""
Parameters
------------
a: :class:`int`
    The first integer
b: :class:`int`
    The second integer

Returns
--------
:class:`int`
    The output

and

@params 
@returns 

etc...
However maybe it's just better to leave it to persona preference

[Cjkjvfnby]

...

[Cjkjvfnby]

However maybe it's just better to leave it to persona preference

Since we don't build documentation for that code we could leave it as is.

80% of these params/returns could be eliminated by annotations and good variable names.

[cclauss]

These all seems fine except maybe the one word sentence. ;-)

I think we should start to auto-generate docs using Sphinx plus sphinx-autodoc-typehints which I have used on other projects with great success. sphinx-autodoc-typehints does a great job of turning type hints into docs.

jjjake/internetarchive#524 (comment)