Đóng góp - MkDocs
Giới thiệu về việc đóng góp cho dự án MkDocs.
Dự án MkDocs chào đón các đóng góp từ các nhà phát triển và người dùng trong cộng đồng nguồn mở. Có thể đóng góp theo nhiều cách, một số ví dụ là:
- Bản vá mã thông qua yêu cầu kéo
- Cải tiến tài liệu
- Báo cáo lỗi và đánh giá bản vá
Để biết thông tin về các kênh liên lạc khả dụng, vui lòng tham khảo tệp README trong kho lưu trữ GitHub của chúng tôi.
Báo cáo sự cố
Vui lòng cung cấp càng nhiều chi tiết càng tốt. Hãy cho chúng tôi biết nền tảng và phiên bản MkDocs của bạn. Nếu vấn đề là về hình ảnh (ví dụ như vấn đề về chủ đề hoặc thiết kế), vui lòng thêm ảnh chụp màn hình. Nếu bạn gặp lỗi, vui lòng bao gồm thông báo lỗi đầy đủ và theo dõi.
Sẽ đặc biệt hữu ích nếu báo cáo vấn đề đề cập đến tất cả các khía cạnh sau:
-
Bạn đang cố gắng đạt được điều gì?
-
Cấu hình của bạn là gì
mkdocs.yml(+ các tệp liên quan khác)? Tốt nhất là giảm xuống mức tối thiểu có thể tái tạo được. -
Bạn mong đợi điều gì sẽ xảy ra khi áp dụng thiết lập này?
-
Thay vào đó, điều gì đã xảy ra và nó không phù hợp với kỳ vọng của bạn như thế nào?
Thử nghiệm phiên bản phát triển
Nếu bạn chỉ muốn cài đặt và dùng thử phiên bản phát triển mới nhất của MkDocs (trong trường hợp nó đã có bản sửa lỗi cho sự cố của bạn), bạn có thể thực hiện bằng lệnh sau. Điều này có thể hữu ích nếu bạn muốn cung cấp phản hồi cho một tính năng mới hoặc muốn xác nhận xem lỗi bạn gặp phải đã được sửa trong git master hay chưa. Chúng tôi đặc biệt khuyến nghị bạn thực hiện việc này trong virtualenv .
pip install git+https://github.com/mkdocs/mkdocs.git
Cài đặt để phát triển
Lưu ý rằng đối với phát triển, bạn chỉ có thể sử dụng Hatch trực tiếp như mô tả bên dưới. Nếu bạn muốn cài đặt bản sao cục bộ của MkDocs, bạn có thể chạy pip install --editable .. Chúng tôi khuyến nghị bạn nên thực hiện việc này trong virtualenv .
Cài đặt Hatch
Công cụ chính được sử dụng để phát triển là Hatch . Nó quản lý các phụ thuộc (trong virtualenv được tạo ra khi đang chạy) và cũng là trình chạy lệnh.
Vì vậy, trước tiên, hãy cài đặt nó . Tốt nhất là theo cách riêng biệt với pipx install hatch(sau khi [cài đặt pipx]), hoặc chỉ pip install hatchlà một cách phổ biến hơn.
Chạy tất cả các kiểm tra
Để chạy tất cả các kiểm tra cần thiết cho MkDocs, chỉ cần chạy lệnh sau trong kho lưu trữ MkDocs đã sao chép:
hatch run all
Điều này sẽ bao gồm tất cả các kiểm tra được đề cập dưới đây.
Tất cả các kiểm tra đều phải đạt.
Chạy thử nghiệm
Để chạy bộ kiểm tra cho MkDocs, hãy chạy các lệnh sau:
hatch run test:test hatch run integration:test
Nó sẽ cố gắng chạy thử nghiệm trên tất cả các phiên bản Python mà chúng tôi hỗ trợ. Vì vậy, đừng lo lắng nếu bạn bỏ lỡ một số. Phần còn lại sẽ được GitHub Actions xác minh khi bạn gửi yêu cầu kéo.
Kiểu mã Python
Mã Python trong cơ sở mã của MkDocs được định dạng bằng Black và Isort và được kiểm tra bằng Ruff , tất cả đều được cấu hình trong pyproject.toml.
Bạn có thể tự động kiểm tra và định dạng mã theo các công cụ này bằng lệnh sau:
hatch run style:fix
Mã cũng được kiểm tra kiểu bằng mypy - cũng được cấu hình trong pyproject.toml, có thể chạy như thế này:
hatch run types:check
Kiểm tra phong cách khác
Có một số kiểm tra khác, chẳng hạn như kiểm tra chính tả và kiểu JS. Để chạy tất cả, hãy sử dụng lệnh này:
hatch run lint:check
Tài liệu của MkDocs
Sau khi chỉnh sửa các tập tin trong thư docs/mục, bạn có thể xem trước trang web cục bộ bằng lệnh sau:
hatch run docs:serve
Lưu ý rằng bất kỳ 'CẢNH BÁO' nào cũng phải được giải quyết trước khi gửi bài đóng góp.
Các tệp tài liệu cũng được kiểm tra bởi markdownlint, vì vậy bạn cũng nên chạy lệnh này:
hatch run lint:check
Nếu bạn thêm một plugin mới vào mkdocs.yml, bạn không cần phải thêm nó vào bất kỳ tệp "yêu cầu" nào, vì điều đó đã được quản lý tự động.
Thông tin
Nếu bạn không muốn sử dụng Hatch, để lập tài liệu, bạn có thể cài đặt các yêu cầu vào virtualenv theo một trong những cách sau (với .venvthư mục virtualenv):
.venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies. .venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies.
Dịch chủ đề
Để bản địa hóa chủ đề sang ngôn ngữ yêu thích của bạn, hãy làm theo hướng dẫn về Dịch chủ đề . Chúng tôi hoan nghênh các yêu cầu dịch thuật!
Gửi yêu cầu kéo
Nếu bạn đang cân nhắc đóng góp mã nguồn lớn cho MkDocs, vui lòng mở một vấn đề trước để nhận được phản hồi sớm về ý tưởng này.
Khi bạn nghĩ rằng mã đã sẵn sàng để được xem xét, hãy đẩy nó vào nhánh của bạn và gửi yêu cầu kéo. Để thay đổi được chấp nhận, rất có thể cần phải có các bài kiểm tra và tài liệu nếu đó là tính năng mới.
Khi làm việc với nhánh yêu cầu kéo:
Trừ khi có thỏa thuận khác, hãy ưu tiên commithơn amend, và mergehơn rebase. Tránh đẩy cưỡng bức, nếu không, lịch sử xem xét sẽ khó điều hướng hơn nhiều. Đối với kết quả cuối cùng, lịch sử "không sạch" là ổn vì hầu hết các yêu cầu kéo đều được hợp nhất trên GitHub.
Không thêm vào release-notes.md , phần này sẽ được viết sau.
Gửi thay đổi cho các chủ đề tích hợp
Khi được cài đặt với i18nhỗ trợ ( pip install 'mkdocs[i18n]'), MkDocs cho phép các chủ đề được hỗ trợ dịch sang nhiều ngôn ngữ khác nhau (được gọi là ngôn ngữ) nếu chúng tôn trọng tiện ích mở rộng i18n của Jinja bằng cách bao quanh các chỗ giữ chỗ văn bản bằng các thẻ {% trans %}và {% endtrans %}.
Mỗi lần một trình giữ chỗ văn bản có thể dịch được được thêm vào, xóa hoặc thay đổi trong một mẫu chủ đề, tệp Mẫu đối tượng di động ( ) của chủ đề potcần được cập nhật bằng cách chạy extract_messageslệnh. Để cập nhật pottệp cho cả hai chủ đề tích hợp, hãy chạy các lệnh sau:
pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs
Tệp đã cập nhật potphải được đưa vào PR với mẫu đã cập nhật. Tệp đã cập nhật potsẽ cho phép những người đóng góp bản dịch đề xuất các bản dịch cần thiết cho ngôn ngữ họ muốn. Xem hướng dẫn về Dịch chủ đề để biết chi tiết.
Ghi chú
Người đóng góp không được yêu cầu cung cấp bản dịch với những thay đổi của họ đối với mẫu của chủ đề. Tuy nhiên, họ được yêu cầu bao gồm một pot tệp đã cập nhật để mọi thứ sẵn sàng cho người dịch thực hiện công việc của họ.
Quy tắc ứng xử
Mọi người tương tác trong cơ sở mã, trình theo dõi sự cố, phòng trò chuyện và danh sách gửi thư của dự án MkDocs đều phải tuân theo Quy tắc ứng xử của PyPA .