文档sphinx编译warning的消除

[luotao1]

文档链接&描述 Document Links & Description

Docs-NEW流水线使用sphinx编译文档，配置项设置keep_warnings=True，并没有将其作为error输出。

docs/ci_scripts/doc-build-config/en/conf.py

Lines 152 to 153 in e4a8e67

	# If true, keep warnings as "system message" paragraphs in the built documents.
	keep_warnings = True

以 某条PR流水线 日志为准，存量问题在不同日志中是一样的。

• 如Error in "code-block" directive错误，存在41处。accuracy_en 的报错在日志中就有。下面两张图分别是官网报错和CI日志报错。

• 如Field list ends without a blank line; unexpected unindent，存在4处。prelu_en的报错在日志中就有。下面两张图分别是官网报错和CI日志报错。

keep_warnings的官方介绍 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-keep_warnings

• If true, keep warnings as “system message” paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.

请提出你的建议/提个PR修复这个问题 Please give your suggestion/update a PR to fix it

Sphinx的warning该如何修复？

• 不建议全部修复。因为目前有1w8条warning，3400多条error，量非常大。且有些类型，如Title underline too short，不影响预览

• 是否有开关可以设置某些warning as error，存量修复完后通过CI限制增量？ 从keep_warnings和suppress_warnings的描述，不是特别清楚如何设置（欢迎大家一起研究👏）

• 比较合理的修复方式：

  1. 根据已经发现的一类问题，寻找报错的关键词，比如 Error in "code-block" directive。在CI日志中进行全量扫描，然后按类修复。可以发现肉眼遗漏的错误部分。
  2. 增量文档预览，都经过TPM的approve，问题不大。目前错误都集中在历史遗留问题上，所以通过步骤1可以解决。