[docs] resolve warnings in docs creation

[jameslamb]

While working on a recent contribution, I followed the directions at https://ml.dask.org/contributing.html#documentation to re-generate this project's documentation. On main, that generates many warnings and errors.

I think resolving these warnings and errors would improve the documentation for dask-ml, and would allow maintainers to make docs checks in continuous integration stricter, to catch issues like broken links before PRs are merged to main.

Current State

I ran the following steps from https://ml.dask.org/contributing.html#documentation to regenerate the documentation.

conda env create -f ci/environment-docs.yaml --name=dask-ml-dev-docs
conda activate dask-ml-dev-docs
python -m pip install -e .
cd docs
make html

This generates the following warnings / errors.

reading sources... [100%] xgboost                                                                    
docs/source/index.rst:92: WARNING: Error in "toctree" directive:
invalid option value: (option: "maxdepth"; value: '2 :hidden: :caption: Get Started')
invalid literal for int() with base 10: '2 :hidden: :caption: Get Started'.

.. toctree:: :maxdepth: 2 :hidden: :caption: Get Started

   install.rst
   examples.rst
WARNING: invalid signature for automodule ('dask_ml.preprocessing.text:')
WARNING: don't know which module to import for autodocumenting 'dask_ml.preprocessing.text:' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: autodoc: failed to import module 'xgboost' from module 'dask_ml'; the following exception was raised:
No module named 'dask_xgboost'
docs/source/modules/api.rst.rst:272: WARNING: autosummary: failed to import XGBClassifier
docs/source/modules/api.rst.rst:272: WARNING: autosummary: failed to import XGBRegressor
docs/source/modules/api.rst.rst:279: WARNING: autosummary: failed to import train
docs/source/modules/api.rst.rst:279: WARNING: autosummary: failed to import predict
docs/source/modules/generated/dask_ml.cluster.KMeans.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.cluster.KMeans.examples'.
docs/source/modules/generated/dask_ml.cluster.SpectralClustering.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.cluster.SpectralClustering.examples'.
docs/source/modules/generated/dask_ml.compose.ColumnTransformer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.compose.ColumnTransformer.examples'.
dask_ml/datasets.py:docstring of dask_ml.datasets.make_blobs:46: WARNING: Unexpected indentation.
dask_ml/datasets.py:docstring of dask_ml.datasets.make_regression:64: WARNING: Unexpected indentation.
docs/source/modules/generated/dask_ml.decomposition.IncrementalPCA.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.decomposition.IncrementalPCA.examples'.
docs/source/modules/generated/dask_ml.decomposition.PCA.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.decomposition.PCA.examples'.
docs/source/modules/generated/dask_ml.decomposition.TruncatedSVD.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.decomposition.TruncatedSVD.examples'.
docs/source/modules/generated/dask_ml.ensemble.BlockwiseVotingClassifier.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.ensemble.BlockwiseVotingClassifier.examples'.
docs/source/modules/generated/dask_ml.ensemble.BlockwiseVotingRegressor.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.ensemble.BlockwiseVotingRegressor.examples'.
docs/source/modules/generated/dask_ml.feature_extraction.text.CountVectorizer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.feature_extraction.text.CountVectorizer.examples'.
docs/source/modules/generated/dask_ml.feature_extraction.text.FeatureHasher.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.feature_extraction.text.FeatureHasher.examples'.
docs/source/modules/generated/dask_ml.feature_extraction.text.HashingVectorizer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.feature_extraction.text.HashingVectorizer.examples'.
docs/source/modules/generated/dask_ml.impute.SimpleImputer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.impute.SimpleImputer.examples'.
docs/source/modules/generated/dask_ml.linear_model.LinearRegression.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.linear_model.LinearRegression.examples'.
docs/source/modules/generated/dask_ml.linear_model.LogisticRegression.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.linear_model.LogisticRegression.examples'.
docs/source/modules/generated/dask_ml.linear_model.PoissonRegression.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.linear_model.PoissonRegression.examples'.
dask_ml/model_selection/_search.py:docstring of dask_ml.model_selection.GridSearchCV:50: WARNING: Unexpected indentation.
docs/source/modules/generated/dask_ml.model_selection.GridSearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.GridSearchCV.examples'.
dask_ml/model_selection/_hyperband.py:docstring of dask_ml.model_selection.HyperbandSearchCV:117: WARNING: Unexpected indentation.
docs/source/modules/generated/dask_ml.model_selection.HyperbandSearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.HyperbandSearchCV.examples'.
docs/source/modules/generated/dask_ml.model_selection.IncrementalSearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.IncrementalSearchCV.examples'.
docs/source/modules/generated/dask_ml.model_selection.InverseDecaySearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.InverseDecaySearchCV.examples'.
docs/source/modules/generated/dask_ml.model_selection.KFold.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.KFold.examples'.
dask_ml/model_selection/_search.py:docstring of dask_ml.model_selection.RandomizedSearchCV:67: WARNING: Unexpected indentation.
docs/source/modules/generated/dask_ml.model_selection.RandomizedSearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.RandomizedSearchCV.examples'.
docs/source/modules/generated/dask_ml.model_selection.ShuffleSplit.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.ShuffleSplit.examples'.
docs/source/modules/generated/dask_ml.model_selection.SuccessiveHalvingSearchCV.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.model_selection.SuccessiveHalvingSearchCV.examples'.
docs/source/modules/generated/dask_ml.naive_bayes.GaussianNB.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.naive_bayes.GaussianNB.examples'.
dask_ml/preprocessing/_block_transformer.py:docstring of dask_ml.preprocessing.BlockTransformer:18: WARNING: Block quote ends without a blank line; unexpected unindent.
docs/source/modules/generated/dask_ml.preprocessing.BlockTransformer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.BlockTransformer.examples'.
docs/source/modules/generated/dask_ml.preprocessing.Categorizer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.Categorizer.examples'.
docs/source/modules/generated/dask_ml.preprocessing.DummyEncoder.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.DummyEncoder.examples'.
docs/source/modules/generated/dask_ml.preprocessing.LabelEncoder.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.LabelEncoder.examples'.
docs/source/modules/generated/dask_ml.preprocessing.MinMaxScaler.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.MinMaxScaler.examples'.
docs/source/modules/generated/dask_ml.preprocessing.OrdinalEncoder.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.OrdinalEncoder.examples'.
docs/source/modules/generated/dask_ml.preprocessing.PolynomialFeatures.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.PolynomialFeatures.examples'.
dask_ml/preprocessing/data.py:docstring of dask_ml.preprocessing.PolynomialFeatures:44: WARNING: Unknown target name: "n_input_features".
dask_ml/preprocessing/data.py:docstring of dask_ml.preprocessing.PolynomialFeatures:53: WARNING: Unknown target name: "n_output_features".
docs/source/modules/generated/dask_ml.preprocessing.QuantileTransformer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.QuantileTransformer.examples'.
docs/source/modules/generated/dask_ml.preprocessing.RobustScaler.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.RobustScaler.examples'.
docs/source/modules/generated/dask_ml.preprocessing.StandardScaler.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.preprocessing.StandardScaler.examples'.
docs/source/modules/generated/dask_ml.wrappers.Incremental.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.wrappers.Incremental.examples'.
docs/source/modules/generated/dask_ml.wrappers.ParallelPostFit.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generated/dask_ml.wrappers.ParallelPostFit.examples'.
dask_ml/compose/_column_transformer.py:docstring of dask_ml.compose.ColumnTransformer:1: WARNING: duplicate object description of dask_ml.compose.ColumnTransformer, other instance in modules/generated/dask_ml.compose.ColumnTransformer, use :noindex: for one of them
dask_ml/compose/_column_transformer.py:docstring of dask_ml.compose.ColumnTransformer.__init__:1: WARNING: duplicate object description of dask_ml.compose.ColumnTransformer.__init__, other instance in modules/generated/dask_ml.compose.ColumnTransformer, use :noindex: for one of them
docs/source/modules/generted/dask_ml.compose.ColumnTransformer.rst:12: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'source/modules/generted/dask_ml.compose.ColumnTransformer.examples'.
dask_ml/compose/_column_transformer.py:docstring of dask_ml.compose.make_column_transformer:1: WARNING: duplicate object description of dask_ml.compose.make_column_transformer, other instance in modules/generated/dask_ml.compose.make_column_transformer, use :noindex: for one of them
docs/source/pytorch.rst:72: WARNING: Duplicate explicit target name: "pytorch".
docs/source/pytorch.rst:6: WARNING: Duplicate target name, cannot be used as a unique reference: "pytorch".
docs/source/xgboost.rst.rst:19: WARNING: autosummary: failed to import train
docs/source/xgboost.rst.rst:19: WARNING: autosummary: failed to import predict
docs/source/xgboost.rst.rst:19: WARNING: autosummary: failed to import XGBClassifier
docs/source/xgboost.rst.rst:19: WARNING: autosummary: failed to import XGBRegressor
looking for now-outdated files... none found
pickling environment... done
checking consistency... docs/source/examples.rst: WARNING: document isn't included in any toctree
docs/source/install.rst: WARNING: document isn't included in any toctree
docs/source/modules/generted/dask_ml.compose.ColumnTransformer.rst: WARNING: document isn't included in any toctree
docs/source/modules/generted/dask_ml.compose.make_column_transformer.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] xgboost                                                                     
docs/source/changelog.rst:12: WARNING: undefined label: pytorch (if the link has no caption the label must precede a section header)

How to close this issue

I'd like to request that maintainers mark this issue "good first issue" and accept contributions that resolve these warnings.

The issue could be closed once it's possible to introduce a change that says "CI builds fail if warnings / errors are generated from building the docs". That could be achieved by setting SPHINXOPTS=-W at

dask-ml/docs/Makefile

Line 5 in f5e5bb4

SPHINXOPTS =

.

Thanks for your time and consideration.

[jrbourbeau]

Thanks @jameslamb! Just added the "good first issue" label

[himanshu007-creator]

i am a first time contributor here, and would like to work on this issue. I sent the PR already. Waiting for a review.