Add style checking for docstrings

[vlejd]

Description

Gensim does not have set up style checks for documentation to match format desired by #1411 .

Here are some options:

• pydocstyle: can check basic docstring format (coma on the end of first line, spaces)
• pylint: with load-plugins=pylint.extensions.docparams it can check if docstring contains Args: and Returns: or Yields: clause. It cal also check if all function parameter were documented. Documentation can be found at https://pylint.readthedocs.io/en/latest/reference_guide/extensions.html.
• flake8: it look like this does not support any form of parameter checking.

I think the best option is to add pylint to travis with correct .pylintrc . The problem is that using two style checkers seems a bit weird. Second problem is, that pylint does not have something like flake8 diff to compare errors in a diff. We would have to run something pylint <old_commit> -rn --load-plugins=pylint.extensions.docparams --accept-no-param-doc=no --disable=C0301 --accept-no-raise-doc=no --accept-no-return-doc=no --accept-no-yields-doc=no > old_errors ; head -n -2 old_errors > old_errors and pylint <new_commit> -rn --load-plugins=pylint.extensions.docparams --accept-no-param-doc=no --disable=C0301 --accept-no-raise-doc=no --accept-no-return-doc=no --accept-no-yields-doc=no > new_errors; head -n -2 new_errors > new_errors to get all errors in the last stage and in the new stage. Then run diff -u old_errors new_errors | grep -E "^\+" to filter only errors that were added.

[vlejd]

@menshikh-iv Any thoughts?

[rasto2211]

@tmylk opened a similar issue couple months ago (issue #1192). Sphinx runs also some checks on docstrings. The sad thing about gensim documentation is that it throws over 100 warnings at the compilation. @souravsingh made PR which got rid of couple warning but it seems that since that time new code brought additional warnings. When I try to compile the documentation I see 112 warnings. Maybe it is also a good idea to add a travis job which compiles the documentation and checks if the new code does not bring new errors and warnings. Maybe just a simple diff is sufficient.

[menshikh-iv]

@vlejd @rasto2211 I think we can add building documentation step to travis (but before we need to fix current errors).

I think doc-checker from pylint will be a good option, but if we will be using it, do we need to run Sphinx build to Travis?

[rasto2211]

Well, I don't see a reason why it is a bad idea.

[menshikh-iv]

The question is whether we add both variants (Sphinx build and pylint doc-check) to travis or pylint only.

[rasto2211]

We still need to use sphinx-build to build the docs so I think it is a good idea to make sure that we don't introduce additional warnings in new commits. I don't think that sphinx checks are subset of pylint checks. Besides that, make html takes only 15 sec. on my machine. I don't think that additional 15 sec. on travis would hurt. Currently, the total build time is around 53 minutes.

[menshikh-iv]

@rasto2211 I agree with you, but we will give errors from all documentation from Sphinx every time. I don't want that Sphinx break Travis every time. As a zero step, we need to fix Sphinx errors.

[mpenkov]

Why can't we use doctest for this?

[menshikh-iv]

I think I can close this, because now

• documentation builds in CI (with "convert warnings to error" option, i.e. no more warnings in the building)
• we have flake8-rst that checks PEP8 on docstring examples

So, next step for improve doc & automatization is #2107