Hướng dẫn create a library in python - tạo một thư viện trong python

Hướng dẫn đầy đủ cho việc tạo thư viện Python, từ đường ống bằng không đến CI/CD và tạo tài liệu tự động.

Ảnh của Juliya Zemlyanaya trên unplash - Biểu tượng gói được thực hiện bởi Freepik từ www.flaticon.com

Bạn có muốn tạo một thư viện và chia sẻ mã của bạn với toàn bộ thế giới? Tuyệt vời! Trong bài viết này, chúng tôi sẽ đi sâu vào việc tạo ra một thư viện và chúng tôi sẽ thấy chi tiết về cách:

- Viết mã chất lượng được xuất bản dưới dạng thư viện. - Lưu trữ thư viện của bạn trên PYPI. - Kiểm tra và triển khai các bản cập nhật tương lai của bạn với đường ống CI/CD. - Tạo một trang web tài liệu tự động từ mã của bạn. - Và cuối cùng, lưu trữ tài liệu này miễn phí trên Readthedocs.
— Host your library on Pypi.
— Tests and deploy your futures updates with a CI/CD pipeline.
— Generate a documentation website automatically from your code.
— And finally, host this doc for free on ReadTheDocs.

Khi kết thúc việc đọc của bạn, thế giới của các thư viện và cách duy trì chúng trong thời gian dài, sẽ không còn giữ bất kỳ bí mật nào cho bạn!

Nhưng trước tiên, hãy để Lừa xem khi nào và tại sao để tạo một thư viện:

Khi nào nên tạo một thư viện?

Khi bạn vừa hoàn thành một dự án dài, đầy những cạm bẫy, nơi bạn cảm thấy đôi khi bất lực để giải quyết một số tình huống nhất định; Bạn đã phải tìm kiếm sâu trong số các bài đăng ít được nâng cấp nhất của StackoverFlow, và kết quả là, bạn đã tạo ra nhiều đoạn mã giải quyết các vấn đề cụ thể.

Tại thời điểm này, bạn có khả năng tạo một thư viện: bạn sẽ chỉ phải sao chép một số mã từ dự án của mình. Dễ!you have the possibility to create a library: You will only have to copy some code from your project. Easy!

Tại sao tạo một thư viện?

Đầu tiên, bởi vì mã bạn đã viết, trong tương lai, sẽ cứu các nhà phát triển khác không trải qua quá trình nghiên cứu dài và tốn kém mà bạn đã làm.

Ngoài ra, nếu mã của bạn cung cấp giao diện cấp cao để giải quyết một số vấn đề, bạn sẽ giúp dân chủ hóa việc giải quyết các vấn đề này cho các lập trình viên ít kinh nghiệm hơn. Do đó, thư viện cấp cao của bạn có thể, ví dụ, trở thành một điểm vào để người khác dễ dàng nhận được kết quả nhanh chóng.

Các nhà tuyển dụng bị thuyết phục - Ảnh của Christina @ wocintechchat.com trên unplash

Và cuối cùng, bởi vì trong sơ yếu lý lịch của bạn và trong một cuộc phỏng vấn, nói rằng bạn dành thời gian rảnh cho các thư viện lập trình và phát triển sẽ không thể phủ nhận hoạt động trong lợi ích của bạn.

Tin chắc? Hãy để Lôi đi đến việc tạo ra lib của bạn!

Bắt đầu: Tối đa hóa khả năng tương thích

Đầu tiên, khi tạo dự án thư viện của bạn trong IDE yêu thích của bạn, hãy sử dụng phiên bản Python cũ hơn, để thư viện của bạn có thể tương thích với càng nhiều quy trình công việc hiện tại càng tốt.

Ví dụ: Python 3.9 được phát hành 2 tháng trước. Nếu bạn quyết định bắt đầu với Python mới này và sử dụng các tính năng mới của phiên bản này, chỉ các nhà phát triển có ứng dụng đã chạy Python 3.9 mới có thể sử dụng thư viện của bạn, vì vậy, rất ít người!

Vì vậy, hãy quay lại một vài phiên bản và lấy Python 3.6.Python 3.6.

Viết mã của bạn

Để giữ cho bài viết này đơn giản, bạn sẽ tạo một thư viện sẽ nhân một số với một số khác. Chỉ có bấy nhiêu thôi.

1. Bắt đầu với một tập lệnh

Viết mã luôn bắt đầu, bằng cách này hay cách khác, với việc viết một kịch bản nhỏ. Giống như cái này bên trái.

Ở dòng 8, bản in sẽ hiển thị số 10.

2. Tái cấu trúc chức năng

Bước này rất đơn giản: Biến tập lệnh của bạn thành một chức năng được ghi chép đẹp mắt.

Bạn phải ghi lại mã của bạn, ngay bây giờ! Hãy dũng cảm, và làm điều đó. Đây là lý do tại sao:Be brave, and do it. Here is why:

Sau đó trong bài viết này, chúng tôi sẽ tự động tạo một trang web với tài liệu dựa trên tài liệu (thông số kỹ thuật) của các chức năng của bạn. Nếu bạn không viết tài liệu của mình ngay bây giờ, bạn sẽ phải làm điều đó sau, bằng cách xem lại tất cả mã của bạn và cố gắng nhớ những gì mỗi dòng làm. Điều này sẽ còn dài hơn và nhàm chán hơn…

Ngoài ra, đối với các nhà phát triển mới làm quen, việc ghi lại các chức năng của bạn giúp bạn cắt bỏ tốt hơn và xác định vị trí của mỗi đoạn mã. Điều này sẽ giúp bạn dễ dàng tạo các đối tượng sau này.

Thư giãn, bạn đã viết mã hướng đối tượng-Ảnh của Joshua Aragon trên Unplash

3. Chuyển đổi thành một đối tượng

Tuyên bố miễn trừ trách nhiệm: Mã sau đây chắc chắn là quá mức cần thiết. Nhưng đối với trình diễn, chúng tôi biến đổi hàm trước đó thành một đối tượng.

Lập trình hướng đối tượng (OOP) giúp bạn có khả năng duy trì mã của bạn dễ dàng hơn, cho bạn trong 6 tháng và cho các nhà phát triển sẽ đóng góp cho thư viện của bạn.

Nhưng lý do chính để viết OOP là khi bạn phát triển một thư viện, bạn cần suy nghĩ: Kiến trúc sẽ làm cho thư viện của tôi dễ sử dụng nhất có thể là gì?What is the architecture that will make my library as easy to use as possible?

Bạn phải đặt mình vào đôi giày của người dùng bằng cách suy nghĩ về cách bạn sử dụng các thư viện khác: bạn thường nhập nó, sau đó bạn nhập một hoặc hai dòng mã vào, và đó là điều đó!

Cố gắng làm cho thư viện của bạn dễ sử dụng và Pythonic. Nếu bạn tưởng tượng mọi thứ chỉ đơn giản là cho người dùng, bạn sẽ viết mã của mình một cách rõ ràng hơn và sẽ dễ dàng hơn để duy trì trong thời gian dài.

Tổ chức thư viện của bạn

Mã thư viện của bạn đã hoàn tất. Bây giờ bạn cần tổ chức nó để nó sẵn sàng được xuất bản.

1. Tạo gói Python

Tạo gói Python và đặt tên cho nó khi bạn muốn người dùng nhập thư viện của mình.

Tạo ra một gói Python với Pycharm - hình ảnh của tác giả

Ví dụ: chúng tôi sẽ tạo gói Medium Medium_Multiply. Nó sẽ chứa tất cả các mã của thư viện của chúng tôi. Và các nhà phát triển khác sẽ có thể nhập thư viện bằng cách viết:

Gói Python là gì?

Gói Python chỉ đơn giản là một thư mục có tệp trống __init__.py bên trong. Một số IDE cung cấp để tạo một gói trực tiếp và chăm sóc tạo tệp init cho bạn.

Tất cả các tệp Python, đối tượng, chức năng và biến được tạo trong một gói có thể được nhập từ bất cứ nơi nào trong dự án của bạn.

2. Di chuyển lớp của bạn vào tệp riêng của nó

Cho đến nay, có lẽ bạn đã viết mã của mình bằng một tệp Main Main.py hoặc ứng dụng của ứng dụng. Nhưng chỉ có mã có trong gói Medium Medium_Multiply, sẽ được xuất bản.

Vì vậy, bây giờ, bạn cần sao chép lớp nhân đa nhân vào một tệp mới, Medium Medium_Multiply/Multiplication.py. Như thế này:

Ví dụ về lớp nhân được chuyển sang nhân.py. Mã vẫn giữ nguyên.multiplication.py. Code stay the same.

3. Gọi thư viện của bạn

Bây giờ bạn có thể bắt đầu sử dụng thư viện của mình như thể bạn là người dùng, bằng cách nhập nó vào Main Main.py của bạn.

Et voilà! Bạn đã hoàn thành việc tạo kiến ​​trúc của thư viện của bạn.

Tiền thưởng: Kích hoạt việc nhập khẩu

Cách mà lớp nhân lên của lớp được nhập khẩu là dài và ô nhục, sẽ không ngắn hơn và đẹp hơn khi nhập nó giống như dòng 5?

Để lưu trữ điều đó, chỉ cần thêm dòng mã sau trong tệp __init__.py của gói Python của bạn:

CẢNH BÁO: Nếu bạn nhập nhiều lớp vào tệp này, thứ tự khai báo có thể quan trọng! Đặc biệt là khi các lớp học của bạn cần các lớp phụ huynh khác để chạy. If you import a lot of classes into this file, the order of the declarations can be important! Especially when your classes need other parent classes to run.

Thư viện của bạn vượt qua các bài kiểm tra - Ảnh của John Cameron trên unplash

Viết các bài kiểm tra

Khi bạn xuất bản thư viện của mình ra thế giới, các nhà phát triển muốn có tài liệu và ví dụ. Nó dễ dàng hơn nhiều để sao chép một ví dụ hơn là đọc toàn bộ thông số kỹ thuật!

Sớm muộn gì bạn cũng sẽ phải viết những ví dụ này và sớm hơn là sau này, các ví dụ của bạn có thể chỉ đơn giản là một bản sao/dán của các bài kiểm tra mà bạn sẽ viết ngay bây giờ.

1. Tạo gói thử nghiệm

Gói thử nghiệm trên mạng và nội dung của nó - hình ảnh của tác giả

Tạo một gói thử nghiệm mới trên mạng của dự án của bạn. Bên trong, tạo một tệp mới có tên là Nhân đa nhân_Tests.Py.

Kiến trúc của dự án của bạn sẽ trông giống như hình ảnh bên trái.

2. Viết ra các bài kiểm tra của bạn

Nếu bạn không quen với nó, viết mã kiểm tra tất cả các trường hợp có thể dài và nhàm chán. May mắn thay, cho bài viết này, bạn chỉ cần sao chép mã sau.

Ở đây, chúng tôi sử dụng các thư viện Python Unittest và Math, hai thư viện Python tích hợp (không cần cài đặt).

Đối tượng nhân cũng được nhập từ thư viện và dòng khởi tạo 9. Các thử nghiệm của chúng tôi sẽ được nhân với 2.

Dòng 16, trước tiên chúng tôi kiểm tra, phép nhân với 0, phải là 0.

Sau đó, dòng 23, phép nhân 5 by 2, phải bằng 10.

Dòng 30, phép nhân số âm, -7 x 2, phải bằng -14.

Sau đó, dòng 37, chúng tôi kiểm tra một số hợp lý không định kỳ, (6/17) nhân với 2.

Cuối cùng nhưng không kém phần quan trọng, trên dòng 44, pi nhân với 2. Bởi vì tại sao không?

Và hai dòng cuối cùng của tệp này là điểm nhập của tập lệnh: họ sẽ khởi chạy việc thực hiện các bài kiểm tra.

3. Chạy các bài kiểm tra

Bạn vừa viết tất cả các bài kiểm tra của bạn! Bây giờ tất cả những gì bạn phải làm là điều hành chúng. Với Pycharm, chỉ cần nhấn một trong các nút màu xanh lá cây được hiển thị trong tệp của bạn hoặc chạy trình khởi chạy ở góc trên cùng bên phải:

Chạy các bài kiểm tra bằng pycharm - hình ảnh của tác giả

Bạn cũng có thể chạy các bài kiểm tra bằng cách nhập dòng này trực tiếp vào bảng điều khiển của mình:

python -m unittest -v tests/multiplication_tests.py

Sau khi được thực hiện, một OK OK được hiển thị trong bảng điều khiển. Điều này có nghĩa là mã của bạn đã vượt qua tất cả các bài kiểm tra mà không có lỗi. Xin chúc mừng!

Tất cả các bài kiểm tra được thông qua - Hình ảnh của tác giả

Thêm một sự phụ thuộc

Bạn sẽ hiếm khi viết một thư viện không có sự phụ thuộc, không sử dụng bất kỳ thư viện hiện có nào khác. Để gắn bó gần hơn với thực tế, giờ đây bạn sẽ nhập và sử dụng Numpy để thực hiện nhân.

1. Chỉnh sửa mã của bạn

Thêm và sử dụng Numpy trong lớp nhân của chúng tôi rất đơn giản:

phép nhân.py mà không có tài liệu - giữ cho mọi thứ đơn giản without documentation — Keep things simple

Để rõ ràng, tài liệu của ví dụ này đã được gỡ bỏ.

Trên dòng 2, Numpy được nhập khẩu và đổi tên thành NP NP.

Dòng 12, thực thi phép nhân và trả về kết quả, được thay thế: np.dot () hiện được sử dụng để nhân một số với một số khác.

2. Thêm yêu cầu.txt

Tệp yêu cầu.txt được sử dụng trong mỗi dự án Python để chỉ định các phụ thuộc của nó. Vì vậy, bạn có thể tạo một ở gốc và thêm một dòng với Numpy Numpy.

Một yêu cầu.txt với Numpy - hình ảnh của tác giả requirements.txt with numpy — Image by author

3. Chạy lại các bài kiểm tra

Sau mỗi lần sửa đổi mã, bạn phải chạy các bài kiểm tra của mình. Trong trường hợp của chúng tôi, các bài kiểm tra vượt qua mà không có vấn đề gì. Thư viện của bạn gần như đã sẵn sàng để được xuất bản! Hãy cùng đi đến bước tiếp theo.

Chuẩn bị cho buổi ra mắt - Ảnh của SpaceX trên Unplash

Chuẩn bị cho việc ra mắt

Bây giờ bạn sẽ thiết lập một đường ống mà mỗi khi bạn đẩy một sửa đổi trên GitHub, sẽ tự động:

- Chạy các bài kiểm tra. - Xuất bản cập nhật thư viện trên PYPI.
— Publish the library update on Pypi.

Tất cả điều này đòi hỏi phải thêm một vài tập tin vào dự án của bạn.

1. Thêm một .gitignore cho github

Trước hết, mã thư viện của bạn cần được xuất bản ở đâu đó nơi mọi người có thể đọc nó và sửa đổi nó, nếu họ muốn. Bởi vì một thư viện sống là nguồn mở, để mọi người có thể đề xuất và thảo luận về sửa đổi. Đối với điều này, chúng tôi sẽ tự nhiên sử dụng GitHub.

Và để tránh các tệp không cần thiết được thêm vào kho lưu trữ của bạn (ví dụ: cấu hình pycham hoặc python env của bạn), bạn sẽ thêm một tệp.

gitignore.io, tự động tạo .gitignore - hình ảnh của tác giả

Bạn có thể làm điều này trên pycharm với plugin .ignore. Hoặc bằng cách tạo một tệp thông qua gitignore.io, sau đó bạn sao chép vào tệp .gitigigigore. Liên kết để tạo tệp.

2. Viết một readme.md chào đón

Tại gốc của dự án của bạn, hãy tạo tệp README.MD.

Một readme.md đơn giản và súc tích - nhấp vào xem Xem RAW RAW để sao chép.README.md — Click on “View raw” to copy.

Tệp này sẽ được hiển thị trên trang PYPI của dự án của bạn, tệp mà nhà phát triển truy cập khi họ tìm kiếm các gói mới.

Do đó, điều quan trọng là Readme của bạn đang chào đón và nó tóm tắt trong một vài dòng cách cài đặt và sử dụng thư viện của bạn!

Bạn có thể viết nó một cách nhanh chóng bằng cách sao chép mã từ Main Main.py của bạn và thêm một vài tiêu đề, như trong ví dụ này.

3. Quan trọng nhất: một setup.py

Tệp setup.py của Google là cụ thể cho việc tạo thư viện: nó sẽ chỉ ra PYPI (chỉ mục gói Python) phiên bản của thư viện của bạn, cũng như rất nhiều siêu dữ liệu khác để tham chiếu.

Bằng cách này, các nhà phát triển sẽ có thể tự động cài đặt gói của bạn bằng lệnh sau:

pip install medium-multiply

Dưới đây là nội dung mà bạn có thể sao chép trong tệp mới Setup.py, tại gốc của dự án của bạn:

Setup.py của thư viện của bạnsetup.py of your library

Trong tập tin này, lên đến dòng 6, trước tiên chúng tôi có nhập khẩu.

Sau đó, lên đến dòng 13, chúng tôi tải nội dung của readme.md được tạo trước đó vào một biến. Bằng cách này, nội dung của readme của bạn sẽ được hiển thị trên PYPI.

Trong dòng 17 và sau, chúng tôi đặt cho thư viện một tên, một phiên bản và một mô tả ngắn.

Hơn nữa, dòng 22, chúng tôi chỉ định URL của trang web chúng tôi sẽ tạo tiếp theo. Tiếp theo là tác giả, email.

Các phân loại, dòng 26, chỉ đơn giản là các thẻ tham chiếu trên PYPI.

Và cuối cùng, dòng 37, chúng tôi tải gói Medium Medium_Multiply, là trung tâm của thư viện. Và chúng tôi chỉ định một lần nữa các phụ thuộc của thư viện này với Numpy Numpy trên dòng 39.

Xuất bản thủ công thư viện của bạn - Ảnh của Andrik Langfield trên unplash

Xuất bản đầu tiên: theo cách thủ công

Trước khi tạo một quy trình xuất bản tự động, thư viện của bạn phải được gửi thủ công đến PYPI ít nhất một lần. Để làm điều này, bạn cần gói Twine Twine, một bộ sưu tập các tiện ích giúp xuất bản thư viện dễ dàng hơn. Cài đặt nó bằng lệnh sau:your library must be manually sent to Pypi at least once. To do this, you need the “twine” package, a collection of utilities which makes the publication of libraries easier. Install it with the following command:

pip install wheel
pip install twine

1. Biên dịch thư viện của bạn

Bây giờ bạn đã sẵn sàng để xây dựng thư viện của bạn. Nhập lệnh sau vào bảng điều khiển của bạn:

python setup.py sdist bdist_wheel

Và hãy để phép thuật xảy ra: Một số thư mục xuất hiện trong dự án của bạn. Don Tiết lo lắng về mớ hỗn độn mà họ tạo ra, bạn sẽ tự do xóa tất cả những thứ này một khi thư viện của bạn đã được gửi đến Pypi lần đầu tiên.you will be free to delete all of these once your library has been sent to Pypi for the first time.

Ba thư mục mới đã được tạo - hình ảnh của tác giả

Các thư mục này chứa nhiều tệp: Trong thư mục Dist Dist, bạn sẽ tìm thấy phiên bản đóng gói của thư viện.

Đây là hai tệp sẽ được gửi đến PYPI.

2. Kiểm tra bản dựng

Nhưng trước đó, bạn có thể kiểm tra xem bản dựng có phù hợp với lệnh ngắn này không:

twine check dist/*

Bảng điều khiển in hai dòng với các đường truyền qua. Thư viện của bạn đã sẵn sàng để cất cánh!

Kiểm tra Twine được thông qua, thư viện của bạn đã sẵn sàng - hình ảnh của tác giả

3. Tải lên để kiểm tra PYPI

Bây giờ bạn đã sẵn sàng để tải lên thư viện của mình trên PYPI. Trước tiên, bạn sẽ tải nó lên PYPI thử nghiệm, để kiểm tra, một lần nữa, mọi thứ đều chính xác. Nếu nó chưa được thực hiện, hãy tạo một tài khoản trên PYPI và trên PYPI thử nghiệm. Sau đó, loại:

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Test Pypi là một công cụ rất hữu ích: nó cho phép bạn xuất bản, kiểm tra và phạm sai lầm, mà không có bất kỳ ảnh hưởng nào đến các gói của bạn được xuất bản trên PYPI thực.

Gói của bạn được tải lên thành công để kiểm tra PYPI - hình ảnh của tác giả

Sau khi bạn nhập lệnh, bạn sẽ được yêu cầu đăng nhập với tên người dùng và mật khẩu bạn đã cung cấp khi bạn tạo tài khoản của mình. Thư viện của bạn sau đó được tải lên để kiểm tra PYPI. Như một xác nhận, liên kết của trang mới được tạo được hiển thị. Xin chúc mừng!

4. Tải lên PYPI

Bạn có hài lòng với kết quả không? Hãy để thế giới khám phá thư viện của bạn: Xuất bản nó trên PYPI thực sự.

twine upload dist/*

Nhập lệnh ở trên, kết nối với Pypi và voilà! Thư viện của bạn được xuất bản. Bây giờ bất cứ ai cũng có thể tải xuống và cài đặt nó với PIP PIP Cài đặt trung bình đa dạng.

Trang pypi của thư viện tuyệt vời của bạn - hình ảnh của tác giả

Triển khai liên tục

Bạn vừa hoàn thành quá trình tải lên thủ công. Đó là thời gian để tự động hóa nó với Travis, một công cụ CI/CD miễn phí cho các kho lưu trữ công cộng được lưu trữ trên GitHub.

Bạn đã có thể tạo một tài khoản trên Travis CI.com và kết nối nó với tài khoản GitHub của bạn.

1. Tăng phiên bản thư viện của bạn

Chúng tôi sẽ xuất bản một bản cập nhật thư viện của bạn. Để làm như vậy, trước tiên bạn phải tăng phiên bản của nó trong tệp setup.py, ví dụ: thay thế, ví dụ, thay thế cho 0.1.0.you must first increment its version in the “setup.py” file: Replace “0.1.0” by “0.1.1”, for example.

2. Tạo tệp .travis.yml

Khi bạn xuất bản dự án của mình trên GitHub, Travis sẽ tải nó xuống máy chủ và thực hiện các hướng dẫn được viết trong tệp .travis.yml. Hãy tiếp tục, tạo tệp mới này ở gốc của dự án của bạn và sao chép các dòng sau:

Một tệp .travis.yml, để nói với travis-ci.com.travis.yml file, to tell Travis-ci.com what to do

Trong tập tin này, dòng 3, trước tiên chúng tôi cho Travis sử dụng phiên bản Python nào.

Trên dòng 8, chúng tôi cập nhật PIP.

Chúng tôi cài đặt các phụ thuộc của thư viện của chúng tôi (dòng 11), để Travis có thể chạy các bài kiểm tra của chúng tôi (dòng 14).

Cuối cùng, từ dòng 16, chúng tôi bảo Travis sử dụng mã thông báo để triển khai nhánh chính của repo trên PYPI. Đoạn mã này là mã sẽ tự động xây dựng và tải lên thư viện.

Các lệnh trong tệp này sẽ được thực thi lần lượt. Nếu một trong số họ trả về một lỗi (ví dụ: các bài kiểm tra của bạn không thành công), Travis sẽ dừng mà không thực hiện các lỗi sau.

Bằng cách này, mỗi lần bạn nhấn một phiên bản mới của thư viện, bạn chắc chắn rằng nó sẽ được triển khai và gửi đến PYPI chỉ khi vượt qua các bài kiểm tra! Đây là một cách tốt để đảm bảo rằng các nhà phát triển khác chỉ nhận được các phiên bản làm việc của thư viện của bạn.it will be deployed and sent to Pypi only if it passes the tests! This is a good way to make sure that other developers only receive working versions of your library.

3. Nhận mã thông báo Pypi của bạn

Bạn cần cung cấp cho Travis mã thông báo PYPI của bạn, để anh ấy có thể đăng nhập vào tài khoản của bạn để cập nhật thư viện.

Thêm mã thông báo API trên PYPI - Hình ảnh của tác giả

Truy cập trang web Pypy. Trong danh mục Cài đặt tài khoản trên mạng, nhấp vào nút Thêm API mã thông báo API.

Đặt tên cho mã thông báo của bạn (ví dụ: triển khai Travis Travis). Trong trường phạm vi phạm vi, chọn thư viện bạn vừa tải lên.

Sau đó nhấp vào trên Thêm Thêm TOKEN. Mã thông báo của bạn được hiển thị, viết nó xuống! Nếu bạn đóng trang web này mà không lưu nó, bạn sẽ phải tạo một trang khác. write it down ! If you close this web page without saving it, you will have to generate another one.

4. Chia sẻ trên GitHub

Pycharm: Chia sẻ một dự án trên GitHub - Hình ảnh của tác giả

Bây giờ xuất bản dự án của bạn trên GitHub, trong một kho lưu trữ công cộng.

Hãy chắc chắn rằng nhánh chính của repo của bạn là Master Master. Bạn có thể thay đổi cài đặt này trên GitHub.

Bạn thích đặt tên cho chi nhánh của bạn là chính? Đừng lo lắng. Chỉ cần thay thế dòng cuối cùng của tệp.

5. Cập nhật Travis của bạn

Đăng nhập vào tài khoản của bạn trên Travis-ci.com. Một bản dựng phải được tiến hành và sẽ kết thúc với một lỗi:

Bản dựng Travis đầu tiên của bạn không thành công. Xem nút khác Tùy chọn ”ở góc trên cùng bên phải - hình ảnh của tác giảMore options” button in the top right corner — Image by author

Điều này là tốt! Travis không thể kết nối với PYPI để tải lên thư viện của bạn vì anh ấy chưa có mã thông báo của bạn. Vì vậy, hãy để thêm nó: Nhấp vào nút Tùy chọn khác (có thể nhìn thấy ở phía trên bên phải của hình ảnh), sau đó trên các cài đặt trên mạng.

Tìm phần Môi trường của các biến Môi trường, và thêm một biến mới có tên là Pypi_Token, với mã thông báo PYPI được tạo trước đó của bạn làm giá trị.

Thêm một biến pypi_token với mã thông báo pypi của bạn làm giá trị - hình ảnh của tác giả

Bây giờ bạn có thể quay trở lại trang trước và nhấp vào Khởi động lại Build Build. Đợi vài giây, bạn sẽ thấy một bản dựng màu xanh lá cây đã xuất hiện.

Bạn vừa thiết lập tích hợp liên tục và triển khai liên tục. Từ giờ trở đi, mỗi khi bạn sẽ đẩy vào chi nhánh Master Master của bạn, Travis sẽ tự động chạy các bài kiểm tra và xuất bản cập nhật thư viện của bạn trên PYPI. Xin chúc mừng!Travis will automatically run the tests and publish the update of your library on Pypi. Congratulations!

Nâng lên! Thư viện của bạn có trên web-Ảnh của SpaceX trên các biểu tượng của Gói, Gói và V-mark do Freepik tạo từ www.flaticon.com

Tài liệu được lưu trữ trên web, tự động

Bây giờ, bạn sẽ thiết lập một hệ thống lưu trữ tài liệu trên readthedocs.org, một dịch vụ miễn phí, với Sphinx, gói Python để tạo tài liệu. Và tất nhiên, bạn muốn hệ thống này tự động cập nhật tài liệu.

Bằng cách này, bạn sẽ gần như không có gì để viết bằng tay. Chỉ cần sao chép và dán một số bài kiểm tra của bạn theo thời gian để làm ví dụ. Và thêm ở đây và có một câu ngắn của giải thích.

Nhắc nhở: Thư viện của bạn không tồn tại, nếu nó không được ghi lại. Làm thế nào các nhà phát triển khác có thể sử dụng nó nếu họ không biết phải gõ cái gì? Your library does not exist, if it is not documented. How could other developers use it if they have no idea of what to type?

1. Cài đặt Nhân sư

Hãy bắt đầu bằng cách cài đặt gói Sphinx, với lệnh sau:

pip install sphinx

Bây giờ, hãy tạo và truy cập vào một thư mục tài liệu của người Viking tại gốc của dự án của bạn. Tôi khuyên bạn nên làm điều này trên dòng lệnh vì sau đó bạn sẽ phải chạy Sphinx thông qua bảng điều khiển:

mkdir docs
cd docs

2. Thiết lập tài liệu của bạn

Đó là thời gian để tạo tất cả các tệp cần thiết để tạo trang web tài liệu của bạn. Và Shpinx sẽ làm điều đó cho bạn, nhờ vào lệnh này:

sphinx-quickstart

Bạn có thể sử dụng các cài đặt mặc định của Sphinx. Nhưng hãy cẩn thận để chỉ định tên của dự án của bạn (ở đây, Medium Medium nhân) và tên của bạn với tư cách là tác giả.to specify the name of your project (here “Medium Multiply”), and your name as author.

Chỉ định tên dự án và tác giả với Sphinx-Quickstart-Hình ảnh của tác giả

Sau khi cài đặt hoàn tất, bạn sẽ thấy một số tệp và thư mục xuất hiện trong thư mục tài liệu của bạn.

DOCS DOCS Thư mục được điền - hình ảnh của tác giả

Bạn có thể bỏ qua những người có tên bắt đầu bằng _underscore: chúng chứa phiên bản được xây dựng, biên dịch của tài liệu của bạn. Bạn không nên đẩy chúng trên GitHub.

3. Chỉnh sửa tệp config.py

Tệp cấu hình rất quan trọng: nếu tài liệu của bạn không hoạt động, nếu bạn có lỗi khi bạn cố gắng xây dựng trang web của mình, thì rất có thể là do lỗi trong tệp Conf Conf.py. Đây là cách bạn cần sửa đổi nó:

Conf.py của bạn đã sửa đổi

Trong tệp ví dụ này, tôi đã cố tình xóa tất cả các nhận xét, ngoại trừ các tiêu đề chính để bạn có thể đặt mình.

Trong phần Cài đặt đường dẫn trên đường, hãy sao chép ba dòng. Đặc biệt chú ý đến dòng 4, nói với Sphinx rằng gốc của dự án không phải là thư mục của Doc Docs, mà là thư mục chính!Pay particular attention to line 4 which tells Sphinx that the root of the project is not the “docs” folder, but the parent folder!

Trong cấu hình chung của người Viking, ba phần mở rộng được thêm vào. Cái đầu tiên cho phép sử dụng Markdown trong Sphinx. Và những cái sau đây cho phép Sphinx tạo tài liệu từ tài liệu về các chức năng của bạn.

Cuối cùng, trong phần Tùy chọn cho đầu ra HTML, chủ đề Sphinx được thay thế bằng cách SPHINX_RTD_THEME, đây là chủ đề được sử dụng phổ biến nhất cho các trang web tài liệu Python.

4. Cài đặt các phụ thuộc còn thiếu

Nếu đây là lần đầu tiên bạn sử dụng spinx, bạn cần cài đặt các phụ thuộc mà chúng tôi vừa chỉ định trong tệp cấu hình. Nhập các lệnh sau:

pip install medium-multiply

0

5. Xây dựng tài liệu của bạn

Đó là thời gian để tạo các trang HTML cho trang web tài liệu trong tương lai của bạn. Đảm bảo rằng bạn đang ở trong thư mục tài liệu trên mạng và nhập lệnh sau:

pip install medium-multiply

1

Sau đó, bạn sẽ thấy tin nhắn tốt đẹp này xuất hiện:

Sphinx Build thành công - Hình ảnh của tác giả

Xin chúc mừng, cài đặt Shpinx của bạn đang hoạt động đúng. Bạn có thể xem trước trang web của mình bằng cách mở tệp index index.html, có thể được tìm thấy trong tài liệu của tài liệu/_build/html.

Tất cả các thành phần Sphinx được kết nối - Ảnh của 🇨🇭 Claudio Schwarz | @purzlbaum trên Unplash

Tạo tài liệu từ mã của bạn

Bạn có thể nhận thấy rằng trang web bạn vừa tạo là trống: tài liệu về các chức năng của bạn bị thiếu! Vì vậy, hãy để ngay bây giờ xem làm thế nào để tự động tạo tài liệu từ các thông số kỹ thuật (tài liệu) của mã của bạn.

1. Tạo cây thư mục

Trong thư mục tài liệu của người Viking, hãy tạo một nguồn phụ của nguồn, sau đó là hai người phụ khác là API API và các ví dụ. Như thế này:

Api api và các ví dụ về các thư mục của người dùng - hình ảnh của tác giả

Chúng tôi sẽ đặt tất cả các tệp tài liệu cụ thể cho dự án của bạn, mà chúng tôi sẽ tạo ngay bây giờ.

2. Liên kết trang web với mã của bạn

Trong thư mục API của API, hãy tạo tệp phép nhân. Các tệp của.

Và có thể sao chép các dòng sau:

nhân.

Tệp này cho phép bạn truy xuất DocString từ lớp nhân, để tạo tự động một trang web với tài liệu.

Nó sẽ được thực thi mỗi khi bạn nhấn mã của bạn trên GitHub, để trang web luôn được cập nhật với mã của bạn!

3. Thêm mục nhập vào tab Điều hướng

Lớp học đẹp của bạn và tài liệu của nó phải được người dùng truy cập. Thêm một mục trong menu Trang web dẫn đến trang mới được tạo, như thế này:

INDEX.RST của bạn được sửa đổi với một liên kết đến trang tài liệu của bạn

Hãy chú ý đến dòng Nguồn/API/phép nhân của chúng tôi mà chúng tôi đã thêm. Đây là đường dẫn đến tệp phép nhân được tạo trước đó, không có phần mở rộng.

Về menu điều hướng

Bạn có thể tạo bao nhiêu phần như bạn muốn trong menu của mình bằng cách sao chép mã sau. Ví dụ: bạn có thể tạo sau này một menu khác, ví dụ, hoặc bắt đầu.

Một phần của index.rst, để xác định menu NAV

Trên Sphinx, một phần của menu bắt đầu với TOCTREE.

Tham số Max MaxDepth xác định độ sâu của màn hình phụ đề.

Và cuối cùng, chú thích của người Viking chỉ đơn giản là tên được đặt cho phần của bạn.

4. Xây dựng tài liệu của bạn

Tái tạo các tệp HTML cho trang web của bạn. Nhập lệnh sau từ thư mục tài liệu trên mạng:

pip install medium-multiply

1

Sau đó, mở tệp tài liệu/_Build/html/index.html, trong trình duyệt của bạn. Tài liệu của bạn được tạo ra!

Các tài liệu tham khảo của lớp nhân của bạn, được tạo từ mã của bạn - hình ảnh của tác giả

Lưu trữ trên Readthedocs

Readthedocs.org là một dịch vụ cho phép bạn xây dựng và lưu trữ tài liệu của bạn miễn phí. Nhiều thư viện phổ biến sử dụng nó, chẳng hạn như rasterio, phế liệu hoặc yêu cầu.

Trong bước cuối cùng này, chúng tôi sẽ lưu trữ trang web được tạo trước đó trên ReadThedocs. Vì vậy, hãy tiếp tục và tạo một tài khoản trên đó.

1. Thêm tệp .readthedocs.yml

Bạn sẽ thêm một tệp cấu hình khác vào gốc của dự án của bạn, có tên là .Readthedocs.yml.

Mục đích của tệp này là nói với Readthedocs cách xây dựng tài liệu của bạn.

Đối với điều này, dòng 9 và 10, nó được yêu cầu sử dụng Sphinx, với đường dẫn đến tệp cấu hình.

Dòng 13 nói với ReadThedocs để tạo phiên bản PDF của trang web.

Và cuối cùng, trên các dòng 17 đến 19, nó được yêu cầu cài đặt các phụ thuộc của thư viện của bạn, để nó có thể chạy nó để lấy lại tài liệu của bạn.

2. Nhập kho lưu trữ của bạn

Truy cập bảng điều khiển Readthedocs của bạn, bằng cách nhấp vào tab Dự án của tôi trong hồ sơ của bạn. Sau đó nhấn Nhập nhập một dự án, như được hiển thị bên dưới:

“Nhập một nút Dự án” trên bảng điều khiển ReadThedocs - hình ảnh của tác giảImport a Project” button on ReadTheDocs dashboard — Image by author

Tìm kho lưu trữ của thư viện của bạn và nhập nó bằng cách nhấn vào++.

Sau đó, chỉ định tên của dự án của bạn (ví dụ: trung bình đa dạng). Nó sẽ được sử dụng để tạo URL của trang web của bạn (Medium Multiply.readthedocs.io '). Và cuối cùng nhấp vào trên tiếp theo.

3. Đẩy đến GitHub

Bây giờ bạn sẽ thúc đẩy các thay đổi cho dự án của bạn trên GitHub. Đảm bảo cam kết tệp .readthedocs.yml. Đối với thư mục tài liệu trên mạng, hãy đảm bảo bạn chỉ gửi các tệp và thư mục được tô sáng màu xanh trong hình dưới đây:

Các tập tin và thư mục để đẩy từ các tài liệu trực tuyến - hình ảnh của tác giả

Nhắc nhở: Các thư mục bắt đầu với một dấu gạch dưới không nên được đẩy trên GitHub. ReadThedocs sẽ xây dựng phiên bản tài liệu của riêng bạn. folders starting with an underscore should not be pushed on Github. ReadTheDocs will build its own version of your documentation.

Đó là nó!

Đợi vài giây trong khi ReadThedocs khôi phục các tệp của bạn và xây dựng trang web của bạn. Làm mới trang Build Build của dự án của bạn cho đến khi bạn thấy đã vượt qua.

Bản dựng được truyền trên Readthedocs - hình ảnh của tác giả

Và đó là nó! Bạn có thể truy cập trang web thư viện của bạn bằng cách nhấp vào nút Xem màu xanh lá cây. Bạn cũng có thể tham khảo trang web của thư viện mà chúng tôi vừa tạo trong bài viết này: trung bình đa dạng.readthedocs.io.

Deep Dive đã hoàn thành - Ảnh của Caroline Hernandez trên unplash

Việc lặn sâu của bạn bây giờ đã hoàn thành!

Bạn chỉ học cách tạo một thư viện vững chắc với các bài kiểm tra; Cách thiết lập một đường ống để nhanh chóng triển khai các bản cập nhật của bạn; Và làm thế nào để dễ dàng xuất bản một trang web với tài liệu cập nhật.

Don Tiết ngần ngại nâng kho lưu trữ của thư viện đa phương tiện, được tạo ra đặc biệt cho bài viết này.

Cảm ơn vì đã đọc! Bất kỳ phản hồi nào được hoan nghênh, bạn có thể liên hệ với tôi ở đây trong các bình luận hoặc trên Twitter: Joffreybvn. Và hãy theo dõi các hướng dẫn thân thiện với người mới bắt đầu hơn.

Làm thế nào để bạn xây dựng một thư viện?

Một ví dụ về thư viện trong Python là gì?

__ init __ py làm gì trong python?