tl.pkg là một mẫu cho một gói Python namespaced với Sphinx docs.
Gói này tạo ra các tập tin và thư mục bố trí cơ bản của gói Python với các tài liệu Sphinx và một buildout phát triển. Nó bao gồm hai phần:
- Một mẫu paste.script mà tạo ra các soạn cho một gói Python sống ở một mức độ không gian tên, và
- Một mô-đun Python được sử dụng để cấu hình Sphinx, cùng với sự phụ thuộc gói cần thiết và một số theming.
Các gói phần mềm làm việc với Python 2.6 và 2.7.
Cách sử dụng
Để làm cho các mẫu paster sẵn, cài đặt tl.pkg nơi paster có thể tìm thấy nó. Sau đó chạy paster:
& Nbsp;. Paster tạo --template tl-pkg
Điều này sẽ tạo ra các soạn cho một phân phối trứng, hoàn chỉnh với cấu hình zc.buildout, bộ xương của tài liệu gói Sphinx, và một kho Mercurial khởi tạo. Các cấu hình buildout là mục tiêu của sự phát triển, do đó, nó sẽ cài đặt một testrunner tại bin / test và một người xây dựng tài liệu hướng dẫn tại bin / doc.
Một số biến sẽ được nhắc nhở cho, trong đó mô tả một dòng và một số từ khóa cho các gói.
riêng
Hơn ba biến paster hỏi bạn đang sử dụng để cá nhân hoá những bộ xương gói nó sẽ tạo ra. Các biến này có thể có giá trị mặc định được đọc từ một tập tin có tên là $ HOME / .tl-pkg.cfg nếu nó tồn tại. Các tập tin cần phải làm theo cú pháp ini-file theo cách hiểu của ConfigParser Python và chứa một phần (với một cái tên tùy ý cho đến nay) mà xác định bất kỳ biến nào sau đây:
Tác giả: Tên đầy đủ của bạn. Điều này sẽ xuất hiện trong các siêu dữ liệu gói và tài liệu cũng như trong các thông báo bản quyền của bất kỳ file Python tạo ra.
tác giả-email: Địa chỉ e-mail của bạn. Điều này xuất hiện cả trong các siêu dữ liệu gói và tài liệu hướng dẫn.
bitbucket-name: tên người dùng của bạn bitbucket. Điều này được sử dụng để xây dựng các URL khác nhau thuộc dự án. Hiện nay, các giả định là dự án được tổ chức tại
Nội dung Gói
Điều này là để giải thích mục đích của các tập tin và thư mục được tạo ra, cùng với lời khuyên về những file đã được chỉnh sửa khi. Nhiều tập tin sẽ không cần phải được chỉnh sửa gì cả.
Phân phối Python
setup.py: Định nghĩa gói và siêu dữ liệu. Cập nhật file này ít nhất là bất cứ khi nào số phiên bản của gói, phụ thuộc, các điểm nhập cảnh thay đổi.
Kho Mercurial
.hg: Các kho Mercurial đã được khởi tạo khi các gói đã được tạo ra. Các tập tin được tạo ra đã không được cam kết nào.
.hg / hgrc: cấu hình Repository trỏ đến URL tương lai của các gói trong một số lưu trữ Mercurial, nếu có. Nó cũng đặt tên người dùng hg của bạn.
.hgignore: Files và thư mục để được bỏ qua bởi Mercurial. Điều này bao gồm cấu hình địa phương và các công cụ dự kiến sẽ được tạo ra bởi buildout, tài liệu hướng dẫn xây dựng hoặc phát hành gói. Nó không bao gồm các tập tin được tạo ra bởi Python (như * pyc), phân phối (* .egg-info), hoặc các công cụ tổng quát hơn khác như biên tập viên của bạn, mà không phải là cụ thể cho dự án này. Mô hình như vậy nên trên Mercurial mặc định của bạn danh sách bỏ qua.
Buildout phát triển
bootstrap.py: Tạo ra các kịch bản bin / buildout. Khởi này với các thông dịch Python tương tự mà buildout nên sử dụng. Không cần thiết phải bao giờ để chỉnh sửa tập tin này.
buildout.cfg: Một cấu hình buildout làm việc tạo ra một Á hậu kiểm tra và xây dựng tài liệu hướng dẫn cho các gói. Các gói phần mềm chính nó được bao gồm như là một quả trứng phát triển và buildout được cấu hình để sử dụng phiên bản chỉ gắn các gói khác nhau. Chỉnh sửa này để cấu hình chính thức buildout phát triển của gói nhưng đặt tùy biến địa phương trong local.cfg. Version pinnings đi trong các phiên bản / versions.cfg trong khi phần các phiên bản của tập tin này chỉ nên lùi lại pinnings của gói được tuyên bố phát triển trứng bằng phần buildout cùng của tập tin này.
local.cfg: số tuỳ địa phương của cấu hình buildout mà không quan tâm đến các nhà phát triển khác. Điều này đang được bỏ qua bởi Mercurial. Nếu bạn thay đổi file này, chạy bin / buildout local.cfg -c từ đó. Trong khi điều này nghe có vẻ cồng kềnh lúc đầu, giữ cấu hình không địa phương trong buildout.cfg và dưới sự kiểm soát phiên bản là quan trọng đối với trường hợp sử dụng như kiểm tra các gói trên một máy chủ liên tục hội nhập.
phiên bản / versions.cfg:
& Nbsp; Version ghim cho bất kỳ gói được sử dụng bởi các buildout mà không phải là một phần của bộ công cụ Zope. Các phiên bản của tl.pkg đó là cần thiết cho việc xây dựng các tài liệu hướng dẫn được gắn vào cùng một phiên bản đã tạo ra các tập tin gói. Khi nâng cấp tl.pkg sau đó, phiên bản này ghim nhu cầu để được cập nhật cùng với bất kỳ tập tin đó đã thay đổi trong mẫu gói giữa các phiên bản. Chỉnh sửa tập tin này để pin các phiên bản của bất kỳ trứng theo yêu cầu của gói của bạn hoặc buildout của bạn.
phiên bản / ztk-phiên bản-X.Y.Z.cfg:
& Nbsp; Một phát hành cố định của bộ công cụ Zope, bao gồm trong phiên bản pinnings của chúng tôi. Giữ một bản sao cục bộ này cho phép xây dựng các buildout mà không cần truy cập mạng. Không được chỉnh sửa tập tin này.
Tài liệu gói chung
Có một số file văn bản được tìm thấy trong thư mục cấp đầu của gói chứa phần tiêu chuẩn của tài liệu và do đó được dự kiến sẽ ở nơi đó và dưới những cái tên cụ thể của mình, và cần phải được độc lập truy cập của Sphinx. Những tập tin này cần phải được tái cấu trúc văn bản có giá trị như chúng đang được xử lý bởi Sphinx khi xây dựng các tài liệu hướng dẫn đầy đủ, ngoại trừ các thông báo bản quyền và giấy phép văn bản đó có đúng nguyên văn.
README.txt: Một cái nhìn tổng quan về mục đích, nội dung và cách sử dụng của gói sẽ là một phần của trang PyPI của nó và các trang chỉ mục của tài liệu. Điều này nên được giữ up-to-date với nội dung gói tại tất cả các lần.
CHANGES.txt: Nhật ký thay đổi đó cần được cập nhật với những thay đổi vào các gói có liên quan đến những người sử dụng của gói. Định dạng của tập tin được hiểu bởi zest.releaser và phiên bản hiện tại của nó (tức là "tip" phiên bản trong kho Mercurial công) sẽ được chỉ đến từ trang PyPI và các tài liệu hướng dẫn xây dựng gói.
ABOUT.txt: Một số gợi ý về các gói phần mềm và tác giả của nó, chẳng hạn như địa chỉ e-mail của người đó và các URL của các tài liệu của gói, PyPI trang, theo dõi vấn đề và mã nguồn cũng như các bản ghi hiện hành. Nó được giả tài liệu sẽ được được công bố cả ở PyPI và tại
COPYRIGHT.txt: Thông tin bản quyền gói: giữ bản quyền bao gồm những năm bản quyền và một số lời khuyên về các giấy phép sử dụng, đó là giấy phép công Zope, phiên bản 2.1 mặc định. Sửa điều này ít nhất để cập nhật những năm qua.
License.txt: Một bản sao của các văn bản chính thức của các giấy phép sử dụng. Không được chỉnh sửa này ngoại trừ việc trao đổi nó cho một giấy phép khác.
Đầy đủ tài liệu, xây dựng sử dụng Sphinx
doc: Tất cả mọi thứ mà chỉ liên quan đến các tài liệu hướng dẫn Sphinx-tạo. Chúng tôi sử dụng các hậu tố .txt cho tập tin đầu vào Sphinx. Trong khi một số công ước tồn tại về nội dung của các thư mục doc, không có gì xấu sẽ xảy ra với phần còn lại của gói nếu bạn sửa đổi nó một cách tự do; chỉ cần đảm bảo nó vẫn còn hợp lệ đầu vào Sphinx.
doc / conf.py: cấu hình Sphinx. Về cơ bản tất cả các giá trị cấu hình theo quy ước và do đó được nhập khẩu từ tl.pkg, vì vậy bạn phải giữ cho nhập khẩu và gọi tl.pkg.sphinxconf nguyên vẹn. Bạn sẽ cần phải chỉnh sửa tập tin này nếu bạn muốn thay đổi một cái gì đó về các siêu dữ liệu hoặc sự xuất hiện của các tài liệu chỉ cho các gói này. Cập nhật các công ước cho tài liệu Sphinx tạo sẽ được mua lại bằng cách nâng cấp tl.pkg.
doc / index.txt: Các trang bìa của các tài liệu. Nó bao gồm tổng quan về các gói tin từ tập tin README.txt cấp cao và một bảng nội dung trỏ đến các phần của tài liệu hướng dẫn đầy đủ. Chúng bao gồm các tài liệu API được tạo ra, một số thông tin meta về gói và ghi nhận thay đổi. Chỉnh sửa tập tin này nếu bạn muốn thêm các phần top-level, ví dụ.
doc / narrative.txt:
& Nbsp; Các tài liệu gốc của tài liệu gói tường thuật. Điều này là nhằm thu thập bất kỳ file doc-test mà cư trú trong các mô-đun Python trong cây mã nguồn của bạn. Bạn cần phải liệt kê các tập tin theo các chỉ thị toctree, tên tài liệu của họ là các mô hình
doc / api.txt: Các tài liệu gốc của các tài liệu API được tạo ra. Các API là tài liệu bán tự động trong đó bạn phải liệt kê trong tập tin này, theo chỉ thị autosummary, tất cả các mô-đun được ghi nhận, trong đó xảy ra tự động từ đó. Một danh sách ví dụ mô-đun nhận xét ra được bao gồm.
doc / overview.txt:
& Nbsp; Một stub để bao gồm các tập tin đầu cấp README.txt. Không cần phải chỉnh sửa tập tin này.
doc / about.txt: thông tin về các gói phần mềm Meta, kết hợp các tập tin đầu cấp ABOUT.txt, COPYRIGHT.txt, và license.txt. Bạn sẽ không cần phải chỉnh sửa tập tin này.
doc / changes.txt:
& Nbsp; Một stub để bao gồm các tập tin CHANGES.txt top-level. Không cần phải chỉnh sửa tập tin này.
doc / requirements.pip:
& Nbsp; Một danh sách trứng Python (trừ Sphinx tự) cần thiết để xây dựng các tài liệu hướng dẫn. Điều này có nghĩa là cho xây dựng các tài liệu hướng dẫn tại
Xây dựng các tài liệu hướng dẫn đầy đủ
Các cấu hình buildout tạo ra một kịch bản cài đặt tại bin / doc mà các cuộc gọi Sphinx để xây dựng các tài liệu hướng dẫn. Để chạy script này, thư mục làm việc hiện tại của bạn phải được root gói. Các kịch bản sẽ đưa các tài liệu được xây dựng vào build / doc / (tương đối so với thư mục cấp đầu của gói). Tùy chọn chuyển cho bin / doc sẽ được thông qua vào các tiềm ẩn sphinx-xây dựng lệnh, nhưng lưu ý rằng đối số vị trí sẽ không hoạt động.
Giá trị Sphinx cấu hình
Theo mặc định, một số phần mở rộng Sphinx được kích hoạt, do đó bạn có thể cấu hình các thêm vào các biến Sphinx cốt lõi:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Bạn có thể ghi đè lên giá trị mặc định từ tl.pkg đơn giản bằng cách thiết lập các biến tương ứng trong conf.py. của bạn Những lời khẩn cầu tl.pkg.sphinxconf.set_defaults cần phải xảy ra ở cuối:
source_suffix = '.foo'
tl.pkg.sphinxconf nhập khẩu
tl.pkg.sphinxconf.set_defaults ()
Ngược lại, sphinxconf cố gắng sử dụng các biến từ conf.py để tính toán các giá trị. Nếu các biến này được quy định, mà còn phải được thực hiện trước khi set_defaults được gọi. Hiện nay, các biến sau đây được công nhận:
_year_started: giá trị bắt buộc đối với năm dự án đã bắt đầu. Điều này mặc định là năm hiện hành (tại thời điểm xây dựng tài liệu hướng dẫn), nhưng nếu nó được quy định khác nhau và từ năm nay, nó được sử dụng để xây dựng một thông báo bản quyền như "2001-2012 tác giả".
_flattr_url: Nếu quy định, điều này được giả định là các URL của một điều flattr cho dự án này và nút đóng góp flattr sẽ xuất hiện ở phía trên cùng của cột menu của tài liệu đầy đủ. Để thêm một nút flattr đến trang PyPI, bỏ ghi chú "Hỗ trợ dự án" mục trong ABOUT.txt và điền vào các URL đó là tốt.
_issuetracker_offline:
& Nbsp; Nếu thiết lập một giá trị đích thực, sự tích hợp bitbucket của hội nhập sphinxcontrib-issuetracker sẽ được sửa đổi để nó sẽ không cố gắng để truy cập vào
Cuối cùng, các mô-đun tl.pkg.sphinxconf định nghĩa một chức năng mà bạn có thể gọi điện để đăng ký module giả nếu tài liệu là được xây dựng trên một hệ thống như
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'gobject', 'gtk')
Yêu cầu :
- Python
Bình luận không