Warnings when building the docs

まず make html を実行し、報告された警告について docs/index.rst と docs/source/ 配下に記載されているファイルを確認します。ドキュメントのビルドで警告が発生しないことを確認したうえで、リポジトリの CI 設定を確認し、警告による失敗、Sphinx nit-picky mode、sphinx-lint を調べます。これらのチェックが CI で正常に実行されれば完了です。

Building the docs locally yields a number of warnings:

% make html
mkdir -p build
PATH=./venv/bin:$PATH sphinx-build -b html -d build/doctrees  . build/html 
Running Sphinx v4.2.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 20 source files that are out of date
updating environment: [new config] 20 added, 0 changed, 0 removed
reading sources... [100%] source/writing_stubs                                                                                              
/Users/jelle/py/typing/docs/index.rst:86: WARNING: Title underline too short.

Type-Hint and Stub Integration
----------------------
/Users/jelle/py/typing/docs/index.rst:86: WARNING: Title underline too short.

Type-Hint and Stub Integration
----------------------
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/jelle/py/typing/docs/source/annotations.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/basics.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/dependencies.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/faq.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/inference.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/introduction.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/type_compatibility.rst: WARNING: document isn't included in any toctree
/Users/jelle/py/typing/docs/source/type_system.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] source/writing_stubs                                                                                               
/Users/jelle/py/typing/docs/source/generics.rst:290: WARNING: undefined label: advanced_self
/Users/jelle/py/typing/docs/source/generics.rst:642: WARNING: undefined label: casts
/Users/jelle/py/typing/docs/source/protocols.rst:510: WARNING: undefined label: async-and-await
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 13 warnings.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.

We should fix these.

Additionally, this should be caught in CI. Some changes to make:

• Make builds fail on any warnings
• Turn on Sphinx nit-picky mode to catch more issues
• Install sphinx-lint to find additional issues

I'll send a PR to fix the warnings but I'm not currently planning to work on the CI improvements.