Warnings when building the docs
Chưa có ai nhận issue này.
- Ngôn ngữ chính
- Python
- Star
- 1.8k
- Fork
- 302
- Merge trung bình
- 23 giờ
- Pull request đã merge (30 ngày)
- 8
Mô tả
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.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Hướng nghiên cứu
Bắt đầu bằng cách chạy make html và kiểm tra docs/index.rst cùng các tệp được liệt kê trong docs/source/ để tìm các cảnh báo đã được báo cáo. Xác nhận rằng quá trình build tài liệu không có cảnh báo, sau đó xem lại cấu hình CI của repository để kiểm tra việc xử lý lỗi do cảnh báo, Sphinx nit-picky mode và sphinx-lint; được xem là hoàn tất khi các kiểm tra này chạy thành công trong CI.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- ci-cd, documentation
- Loại issue
- Tài liệu
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 42/100