search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.25k stars 2.04k forks source link

Repeat offending warnings at the end of logs #11257

Open astrojuanlu opened 1 year ago

astrojuanlu commented 1 year ago

Is your feature request related to a problem? Please describe. I'm always frustrated when my Sphinx builds fail because of warnings, and it's difficult to locate said warnings.

End of output looking similar to:

copying images... [ 98%] visualisation/../meta/images/pipeline_visualisation_matplotlib.png
copying images... [100%] visualisation/../meta/images/pipeline_visualisation_matplotlib_expand.png

copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 3 warnings.

My trick is usually to Ctrl/Cmd+F for warning:, filter through the noise, and try to locate the actual warnings. But it's really annoying and most Sphinx users don't know how to do this and get frustrated, since the logs are usually quite large.

This has been going on forever, but I found this problem again at https://github.com/kedro-org/kedro-plugins/issues/134 so I decided to open a feature request here.

Describe the solution you'd like Sphinx repeating at the end of the logs what warnings caused the build to fail. Something like:

copying images... [ 98%] visualisation/../meta/images/pipeline_visualisation_matplotlib.png
copying images... [100%] visualisation/../meta/images/pipeline_visualisation_matplotlib_expand.png

copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 3 warnings:

/home/docs/checkouts/readthedocs.org/user_builds/kedro/envs/2425/lib/python3.7/site-packages/kedro/datasets/json/json_dataset.py:docstring of kedro.datasets.json.json_dataset.JSONDataSet:12: WARNING: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/kedro/envs/2425/lib/python3.7/site-packages/kedro/datasets/json/json_dataset.py:docstring of kedro.datasets.json.json_dataset.JSONDataSet:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/kedro/envs/2425/lib/python3.7/site-packages/kedro/datasets/spark/spark_hive_dataset.py:docstring of kedro.datasets.spark.spark_hive_dataset.SparkHiveDataSet:9: WARNING: Bullet list ends without a blank line; unexpected unindent.

Describe alternatives you've considered One alternative could be not repeating the warnings, but giving the user a hint of how to look for them. Something like:

copying images... [ 98%] visualisation/../meta/images/pipeline_visualisation_matplotlib.png
copying images... [100%] visualisation/../meta/images/pipeline_visualisation_matplotlib_expand.png

copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 3 warnings. [Insert explanation here]

But I think this is suboptimal.

Additional context Add any other context or screenshots about the feature request here.

jdillard commented 1 year ago

Another alternative, depending on how much control you have over your build process, is to use the -w flag and then cat the file out after the build process is done.

astrojuanlu commented 1 year ago

You surely mean lowercase -w :) but this is a great tip, thanks @jdillard!

Too bad support for custom build.commands on Read the Docs is still in beta https://docs.readthedocs.io/en/stable/build-customization.html#override-the-build-process but I'll revisit this idea in a few months

jdillard commented 1 year ago

ha whoops (ChatGPT isn't the only one that hallucinates), fixed it! Always happy to see the improvements RTD is making!