Hacktoberfest 2026：維護者為十月標記出來的 issue，仍然開放、適合新手。 瀏覽 Hacktoberfest issue

Warnings when building the docs

未關閉
  • 哪裡不對？
#1,513 0 則留言 1 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

評估

難度
4/5
預估耗時
3-5 天
新手友好度
42/100
Issue 類型
文件
描述清晰度
基本清楚
活躍度
停滯
技術堆疊
python
領域
ci-cd, documentation

研究方向

首先執行 make html，並檢查 docs/index.rst 以及 docs/source/ 下列出的檔案，尋找回報的警告。確認文件建置沒有警告，然後檢查儲存庫的 CI 設定，確認警告導致的失敗、Sphinx nit-picky mode 和 sphinx-lint；這些檢查在 CI 中成功執行即表示完成。

由索引模型根據 Issue 內容生成。

描述

topic: documentation

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.

主要語言
Python
星號
1.8k
分支
302
平均合併
4 小時 2 分鐘
30 天內合併 PR
7

環境準備

這個專案沒有提供開發容器、Dockerfile 或貢獻指南，環境需要你自己搭建：先看它的 README，通用步驟見我們的新手貢獻指南。

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

python/typing 的其他 Issue

查看 python/typing 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。