[Issue-571] make docs errors/warnings fixes

[yromanyshyn]

resolves #571

Summary

Stats:

• WARNINGs during build: 503
• ERRORs during build: 8

ERRORs

---

error type 1 (count: 5, left unfixed)

example:

/home/yura/Projects/deepchecks/deepchecks/docs/source/examples/use-cases/phishing_urls.ipynb:15: ERROR: Content block expected for the "raw" directive; none found.

happens during notebooks pre-processing. It probably means that
nbsphinx generated empty .. raw:: directives, without a content block.
Do not know what effect it has or how to fix this/

Think, not worth spending time on it (at least currently)

error type 2 (count: 3, fixed)

example:

<module-file-path>.py:docstring of <module-name>:11: ERROR: Unexpected indentation.

unexpected indentation in the docstring.

WARNINGs

---

warning type 1 (count: 5, fixed)

example:

/home/yura/Projects/deepchecks/deepchecks/docs/source/api/generated/deepchecks.checks.integrity.CategoryMismatchTrainTest.rst:64: WARNING: toctree contains reference to nonexisting document 'examples/checks/integrity/category_mismatch_train_test'
/home/yura/Projects/deepchecks/deepchecks/docs/source/api/generated/deepchecks.checks.integrity.NewLabelTrainTest.rst:64: WARNING: toctree contains reference to nonexisting document 'examples/checks/integrity/new_label_train_test'
/home/yura/Projects/deepchecks/deepchecks/docs/source/api/generated/deepchecks.checks.integrity.SpecialCharacters.rst:61: WARNING: toctree contains reference to nonexisting document 'examples/checks/integrity/special_characters'
/home/yura/Projects/deepchecks/deepchecks/docs/source/api/generated/deepchecks.checks.methodology.IndexTrainTestLeakage.rst:61: WARNING: toctree contains reference to nonexisting document 'examples/checks/methodology/index_train_test_leakage'
/home/yura/Projects/deepchecks/deepchecks/docs/source/api/generated/deepchecks.checks.methodology.ModelInferenceTimeCheck.rst:61: WARNING: toctree contains reference to nonexisting document 'examples/checks/methodology/model_inference_time_check'

we automatically generate references to the example
notebooks for the checks API pages, to make it work
properly we need to make sure that notebook names are
the same as checks names (but in snake case)

I fixed this

warning type 2 (count: 8, left unfixed)

example:

WARNING: [autosummary] failed to import deepchecks.base.suite.ModelComparisonSuite.checks.
WARNING: [autosummary] failed to import deepchecks.base.suite.ModelComparisonSuite.name.

It happens during autosummary stub files generation, because
sphinx tries to import something that cannot be imported.

The reason for this is that autosummary provides incorrect
variables to the jinja template/ (That is probably a bug, because
it happens only for the inherited attributes)

As a result of this, checks, and name attributes are not
displayed on the Suite API Reference page.

not worth spending time on it currently, will create a separate issue for this

warning type 3 (count: 107, left unfixed)

example:

WARNING: duplicate label <string>, other instance in <doc-path>.rst

indicates that documentation contains two or more identical titles.

In sphinx we can refer to other documents parts by their title with help of the :ref: role,
but it will not work properly if title duplicates exist, therefore sphinx prints a warning (I think/)

sphinx ref role docs

warning type 4 (count: 348)

example:

<module-file-path>.py:docstring of <routine-name>:: WARNING: py:class reference target not found: pandas.core.series.Series

napoleon extension tries to generate links for all function parameter
types within docstring, when he fails he prints a warning

most of the warnings that I saw in the output were related to the cases
when it tried to generate a link to the third party routines, like pandas
or numpy.

I tried to use napoleon_type_aliases config option to actually generate
links to other docs, but it worked partially/ links were present only on a few pages.
So, I abandoned that idea

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[yromanyshyn]

update: I added suppress_warnings option to the conf.py as result, warning types 3 and 4 are suppressed (ignored) now.