dask / dask/dask-ml

[docs] resolve warnings in docs creation

Open
#821 2 comments 0 reactions 0 assignees View on GitHub
good first issue
Dominant language
Python
Stars
951
Forks
262
PR merge metrics
No merged PRs in 30d

Description

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.

```shell
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.

```text
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 https://github.com/dask/dask-ml/blob/f5e5bb4d4d21782b0e93f0f6541e6f2501b0c06c/docs/Makefile#L5.

Thanks for your time and consideration.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.