Làm cách nào để tạo vai trò/vai trò toàn cầu trong Sphinx?

Question

Đây là phần tiếp theo của "ReST Strikethrough" ReST strikethrough nhưng trong ngữ cảnh Sphinx chứ không phải ReST. Câu hỏi của tôi là liệu có một vị trí trung tâm trong nhân sư, nơi đặt một chỉ thị "vai trò" hay liệu chỉ thị này thực sự phải được lặp lại trong mọi tệp đầu tiên trong một quy trình nhân sư.

Cụ thể hơn:

Nó rất dễ dàng để xác định phong cách tùy chỉnh CSS cho văn bản inline (xem phần còn lại Strikethrough làm ví dụ) sử dụng một chỉ thị vai trò:

.. role:: custom 
    :class: custom 

This is an :custom:`inline text`. 

mà chuyển thành một render html của

.. This is an <span class="custom">inline text</span>. .. 

Ngoài ra, biểu định kiểu tùy chỉnh có thể dễ dàng được thêm vào nhân sư (xem http://www.tinkerer.me/doc/theming.html) nơi thêm bộ chọn lớp CSS để kiểm soát văn bản "tùy chỉnh" được hiển thị (màu, gạch ngang, phông chữ, kích thước ...)

Điều làm tôi lo ngại là trong các thử nghiệm của mình, tôi phải lặp lại chỉ thị vai trò trong mỗi tệp ReST sử dụng vai trò tùy chỉnh. Có một "trung tâm" nơi mà tôi có thể xác định điều này một lần cho toàn bộ trang web?

Answer 1

Có vẻ như rst_prolog được đặt trong tệp conf.py là vị trí trung tâm mà tôi đang tìm kiếm. Rst_prolog là "Một chuỗi các reStructuredText sẽ được bao gồm ở đầu mỗi tập tin nguồn được đọc". Trong trường hợp của tôi, tôi chỉ đơn giản là thêm vào phần sau đây để conf.py:

rst_prolog = """ 
.. role:: test2 
""" 

Cũng lưu ý rằng vì mục đích của tôi, vai trò chỉ thị mà không có một attibute lớp hoạt động tốt.

Rõ ràng, như Chris đã chỉ ra, một rst_prolog hoàn thành nhiều thứ có thể đạt được bằng cách bao gồm tệp tin toàn cầu.rst. [Tuy nhiên, có thể có vấn đề với đường dẫn tương đối của nó. Có thể tốt hơn để sử dụng rst_prolog = open ('global.rst', 'r'). Read() --untested]

Answer 2

Từ ví dụ tại documenting your project using sphinx, bạn có thể sử dụng include để thay thế tệp global.rst, chứa tất cả chỉ thị vai trò của bạn, vào các tệp khác của bạn. Từ trang này:

Cú pháp:

.. include:: myfile.rst 

Will "inline" các tập tin nhất định (myfile.rst). Quy ước chung tôi sử dụng là tạo tệp .rst toàn cầu có tên là global.rst và bao gồm nó ở đầu mỗi trang. Rất hữu ích cho các liên kết đến hình ảnh phổ biến hoặc các liên kết tệp thông thường, v.v.