Trăn học viện runestone

Runestone phiên bản 6

Tháng 12 năm 2021 quan trọng - hợp nhất Runestone 6 thành nhánh chính. trong runestone 6. 0 chúng tôi cho rằng bạn đang sử dụng máy chủ sách mới để phục vụ sách. Điều này được cài đặt tự động như một phần của bản dựng Docker trong RunestoneServer chính. Nhưng bạn cũng có thể cài đặt máy chủ sách để chạy một máy chủ quy mô nhỏ sử dụng sqllite. Cuối cùng, máy chủ đặt sách sẽ thay thế máy chủ siêu đơn giản mà bạn nhận được khi chạy phục vụ runestone

Tài liệu

Viết sách mới bằng ngôn ngữ đánh dấu Runestone RST không được chấp nhận kể từ Mùa hè năm 2022. Bạn nên sử dụng ngôn ngữ đánh dấu PreTeXt để viết sách mới

• Hãy xem Sách mẫu Đặc biệt là Chương 3, phần có tiêu đề Bài tập tương tác. Mã kích hoạt, CodeLens và tất cả phần tương tác còn lại mà bạn thấy trong sách mẫu đó được cung cấp bởi các thành phần trong kho lưu trữ này. Kho lưu trữ này sẽ vẫn là ngôi nhà của những thành phần tương tác đó

• Hãy xem Hướng dẫn PreTeXt Nó chứa tài liệu toàn diện về viết bằng PreTeXt

• Là một Tác giả, bạn sẽ muốn sử dụng PreTeXt CLI để viết sách. Các tác giả Runestone có kinh nghiệm sẽ thấy cli cớ khá quen thuộc, nhưng được tổ chức tốt hơn với ít tệp cấu hình bí ẩn hơn. Xem PreTeXt CLI

Bắt đầu nhanh

• lấy cớ cài đặt pip

• Tạo một thư mục cho dự án sách của bạn rồi chạy

• lý do mới để tạo một cuốn sách mới

Tài liệu cũ

Tôi sẽ giữ điều này trong một thời gian trong quá trình chuyển đổi sang PreTeXt

Để bắt đầu với Runestone đã tái cấu trúc Văn bản làm ngôn ngữ đánh dấu

Để bắt đầu một dự án, hãy tạo một thư mục mới và sau đó chạy lệnh sau [được cài đặt bởi pip] trong thư mục mới đó runestone init Ví dụ:

mkdir myproject
cd myproject
runestone init

Lệnh init sẽ hỏi bạn một số câu hỏi và thiết lập một dự án mặc định cho bạn. Phản hồi mặc định nằm trong ngoặc vuông, ví dụ [false]

Để xây dựng chạy dự án mặc định đi kèm

runestone build

Ghi chú. Nếu bạn gặp xung đột phiên bản với sáu thư viện trong khi xây dựng dự án, lệnh pip install --ignore-installed six có thể hữu ích

Bây giờ bạn sẽ có một thư mục bản dựng với chỉ mục tệp. html trong đó, cùng với một số nội dung mặc định. Nội dung của thư mục bản dựng phù hợp để lưu trữ ở mọi nơi mà bạn có thể phục vụ nội dung web tĩnh từ đó. Đối với một lớp nhỏ, bạn thậm chí có thể phục vụ nội dung bằng máy chủ web Python được cung cấp

$ runestone serve

Bây giờ từ trình duyệt của bạn, bạn có thể mở http. //máy chủ cục bộ. 8000/chỉ số. html Bạn sẽ thấy mục lục cho một trang mẫu như thế này

Nếu bạn chỉnh sửa _sources/index. html hoặc _sources/tổng ​​quan. đầu tiên, sau đó xây dựng lại và phục vụ lại, bạn sẽ thấy các thay đổi của mình. Tài liệu tốt nhất có lẽ là tổng quan. rst, vì nó trình bày cách sử dụng tất cả các thành phần phổ biến và hiển thị hầu hết các tùy chọn của chúng

Người dùng Windows Tôi đã thử nghiệm cài đặt, cùng với khởi tạo, xây dựng và phục vụ trên Windows 8. 1. Nỗi đau lớn nhất có lẽ là đặt biến môi trường PATH của bạn để bạn có thể chỉ cần nhập các lệnh từ trình bao. Xin lưu ý rằng tôi không phải là người dùng thường xuyên của windows, tôi chỉ thường xuyên kiểm tra mọi thứ trên bản cài đặt VMWare của mình. Nếu bạn chưa quen với việc sử dụng Python trên windows, tôi khuyên bạn nên xem liên kết này trên Sử dụng Python với Windows

Phát triển và hack

Vì vậy, bạn muốn giúp phát triển các Thành phần Runestone. Tuyệt vời Chúng tôi hoan nghênh mọi sự giúp đỡ mà chúng tôi có thể nhận được. Có rất nhiều việc phải làm bất kể mức độ kinh nghiệm của bạn. Có một vài điều kiện tiên quyết

1. Bạn sẽ cần một phiên bản Python, tôi hiện đang phát triển trên 3. 9 hoặc cao hơn, nhưng kiểm tra trên 3. 8 trở về sau

2. Bạn cũng sẽ cần nodejs và npm vì có RẤT NHIỀU mã Javascript trong các thành phần

Để thiết lập mọi thứ, hãy làm như sau

1. Tạo một nhánh của kho lưu trữ này. và git sao chép kho lưu trữ vào máy phát triển của bạn

2. cài đặt thơ

3. Từ thư mục RunestoneComponents cấp cao nhất, hãy chạy cài đặt npm, thao tác này sẽ cài đặt các công cụ đóng gói cần thiết để phát triển Javascript. npm run cung cấp cho bạn một danh sách các lệnh. Lệnh chính là npm run build lệnh này sẽ kết hợp tất cả các tệp Javascript và CSS cho tất cả các thành phần thành một runestone duy nhất. tập tin js. Nếu bạn đang thực hiện một số bước phát triển thực sự sâu và muốn tránh xây dựng một cuốn sách, bạn có thể đặt html của mình ở chế độ công khai/chỉ mục. html và sử dụng lệnh npm run start. Điều này sẽ tự động xây dựng lại runestone. js và làm mới trang web mỗi khi bạn lưu thay đổi

4. Khi bạn có một số thay đổi để chia sẻ, hãy tạo Yêu cầu kéo

[Xem kho RunestoneServer và http. //runestoneinteractive. org để có tài liệu đầy đủ hơn về cách thức hoạt động của dự án này. ]

Kiểu mã

Chúng tôi sử dụng màu đen để tự động tạo kiểu cho Python. Bạn có thể thiết lập trình chỉnh sửa của mình để tự động chạy màu đen bất cứ khi nào bạn lưu hoặc bạn có thể chạy thủ công

Chúng tôi sử dụng đẹp hơn để tự động tạo kiểu cho Javascript

Chạy jshint trên mã của bạn, chúng tôi có một số tùy chọn được định cấu hình cho dự án này

Kiểm tra viết

Một cách tuyệt vời để đóng góp vào kho Linh kiện Runestone là thêm vào bộ thử nghiệm của chúng tôi

Mục tiêu của chúng tôi là có các bài kiểm tra đơn vị dựa trên Selenium [một thư viện giúp mô phỏng các tương tác trong trình duyệt web] cho từng lệnh, để xem liệu JavaScript hỗ trợ các lệnh đó có hoạt động chính xác không

Để bắt đầu viết bài kiểm tra/viết bài kiểm tra bổ sung, bạn sẽ cần những thứ sau

• Tải xuống ChromeDriver mới nhất. , là trình điều khiển mô phỏng Google Chrome

• Trên linux, bạn sẽ cần cài đặt Xvfb apt-get install xvfb

• Bạn cũng cần phải thực hiện cài đặt ở trên

• Chúng tôi đã chuyển đổi sang sử dụng thơ để quản lý sự phụ thuộc của mình. Để chạy runestone trong khi ở chế độ phát triển, thơ hãy chạy runestone… HOẶC bạn có thể chạy thơ shell để khởi động shell với môi trường ảo được kích hoạt

Hai lần chạy thử

• Đảm bảo thư mục chứa tệp thực thi ChromeDriver nằm trong biến môi trường PATH của bạn. e. g. ĐƯỜNG=$ĐƯỜNG. path/to/chromedriver tại dòng lệnh của bạn [hoặc chỉnh sửa. bash_profile]

• Kiểm tra các bài kiểm tra hiện có, e. g. câu hỏi kiểm tra. py kiểm tra chỉ thị Câu hỏi mà bạn có thể tìm thấy tại đường dẫn /runestone/question/test/test_question. đáng tiếc, ví dụ

• Bộ kiểm tra riêng của mỗi chỉ thị yêu cầu một cuốn sách nhỏ. Bạn sẽ thấy thư mục _sources cho mỗi thử nghiệm hiện có chứa chỉ mục. tập tin đầu tiên. Tập tin đó chứa một tiêu đề, theo yêu cầu của. rst và bất kỳ ví dụ chỉ thị nào bạn muốn kiểm tra

• Cuối cùng, để chạy thử nghiệm, đảm bảo rằng bạn đã truy cập thư mục chỉ thị, hãy nhập nội dung sau tại dấu nhắc lệnh

Chạy pytest từ thư mục chính sẽ chạy tất cả các bài kiểm tra. Để chạy một bài kiểm tra, bạn có thể điều hướng đến thư mục của bài kiểm tra hoặc bạn có thể chạy thơ run pytest -k XXX trong đó XXX là một chuỗi con khớp với một số phần của tên chức năng kiểm tra

Sau đó, bạn sẽ thấy một số đầu ra thử nghiệm, hiển thị đạt [ok], KHÔNG ĐẠT hoặc [các] lỗi

Nếu bạn gặp lỗi liên quan đến PhantomJS/trình điều khiển ở đầu ra, có thể bạn gặp sự cố về cài đặt trình điều khiển hoặc PATH

Để viết một bài kiểm tra mới

• Tạo một thư mục kiểm tra bên trong thư mục của chỉ thị

• Tạo một tệp Python để chứa bộ kiểm tra bên trong thư mục đó, e. g. test_directivename. tiểu

• Chạy runestone init bên trong thư mục đó và trả lời các lời nhắc sau

• Viết [các] ví dụ chỉ thị thích hợp bên trong chỉ mục. tệp đầu tiên [sẽ được tạo do runestone init]

• Chỉnh sửa tệp Python bạn đã tạo cho phù hợp [xem tài liệu về mô-đun unittest Python Trong tài liệu Python. ]

Ghi chú cho người dùng nâng cao hơn

Nếu bạn đã có sẵn một dự án Nhân sư và bạn muốn kết hợp các thành phần runestone vào dự án của mình, bạn chỉ cần thực hiện một vài chỉnh sửa đơn giản đối với conf hiện tại của mình. tập tin py

• Trước tiên, thêm dòng nhập sau từ runestone import runestone_static_dirs, runestone_extensions

• Sau đó sửa đổi tiện ích mở rộng của bạn. Bạn có thể đã bật một bộ tiện ích mở rộng khác, nhưng không thành vấn đề, chỉ cần làm điều này. tiện ích mở rộng = ['nhân sư. mở rộng. mathjax'] + runestone_extensions[]

• Sau đó sửa đổi html_static_path của bạn. html_static_path = ['_static'] + runestone_static_dirs[] Một lần nữa, bạn có thể có bộ đường dẫn tĩnh của riêng mình trong danh sách ban đầu

Xem https. //github. com/bnmnetp/runestone/wiki/DevelopmentRoadmap để hiểu được tất cả điều này sẽ kết hợp với nhau như thế nào

Các nhà nghiên cứu

Nếu bạn sử dụng Runestone trong Nghiên cứu của mình hoặc viết về nó, vui lòng tham khảo https. // đá rune. học viện và trích dẫn bài viết này