Sphinx використовує інтерпретовані ролі тексту для вставки семантичної розмітки в документи. Вони описуються як: rolename: `content`.
Роль за умовчанням ( `content`) за замовчуванням не має ніякого спеціального значення. Ви можете використовувати її для чого завгодно. Використовуйте значення конфігурації: confval: `default_role` для прив'язування цього до відомої ролі.
Дивіться domains. де описано додавання ролей в домени.
Синтаксис крос-ссилок¶
Є деякі додаткові можливості, які дозволяють зробити крос-посилання більш гнучкими:
. текстом посилання буде тільки останній компонент мети. Наприклад,: py: meth: `
Queue.Queue.get` буде посилатися на Queue.Queue.get але в якості текта буде відображатися тільки get.
В HTML виведення, атрибут посилання title (то, що показується при наведенні мишки на посилання) завжди буде повним ім'ям мети.
Об'єкти на крос-ссилкі¶
Наступні ролі описані у відповідних доменах:
Довільне розташування крос-ссилок¶
Для забезпечення можливості посилатися на довільні місця в будь-якому документі, використовуються стандартні мітки (labels) reST. Для того, щоб це працювало імена міток повинні бути унікальними в межах всієї документації. Є два способи, якими Ви можете послатися на мітки:
Якщо Ви розташували мітку безпосередньо перед заголовком розділу, то Ви можете послатися на неї за допомогою: ref: `label-name`. наприклад:
Автоматичні мітки також працюють з фігурами (figures):
В такому випадку: ref: `my-figure` вставить посилання на фігуру з текстом посилання" Тема фігури ".
Те ж саме працює і для таблиць із зазначеним заголовком, для цього потрібно використовувати директиву: dudir: `table`.
Мітки, що не розташовані перед заголовком розділу проте можна використовувати для посилань, але в такому випадку Ви повинні вказати для посилання заголовок за допомогою такого синтаксису:: ref: `Link title
Використання ref більш переважно, ніж стандартні посилання reStructuredText на розділ (наприклад, `Section title`_), так як перший спосіб буде працювати і в разі зміни заголовка розділу і працює для всіх" збирачів ", що підтримують крос-посилання.
Крос-посилання на документи¶
New in version 0.6.
Крім усього вищесказаного є спосіб безпосередньо посилатися на документи:
Якщо текст посилання не вказано (на відміну від, наприклад:: doc: `Monty Python members `), То в якості нього буде використовуватися заголовок документа.
Посилання на завантажувані файли¶
New in version 0.6.
Ця роль дозволяє послатися на файли, які не є документами reST і які можна скачати.
Коли Ви використовуєте цю роль, то посилається файл автоматично позначається для включення в висновок при складанні (очевидно, це актуально тільки для HTML виведення). Всі файли, що завантажуються поміщаються в підкаталог _downloads вихідного каталогу; повторювані імена файлів обробляються (duplicate filenames are handled).
Файл вказується зазвичай щодо файлу, що містить цю директиву; але якщо він вказаний в абсолютному вигляді (починаючи з /), то він розглядається щодо каталогу з вихідними файлами.
Крос-посилання на інші елементи¶
Наступні ролі дозволяють створювати крос-посилання, але при цьому вони не посилаються на конкретні об'єкти:
Ім'я граматичного токена (grammar token) (використовуєте для створення посилань між директивами productionlist).
Ім'я ключового слова Python. Створює посилання на посилається мітку з цим імененем, якщо вона існує.
Опція командного рядка для виконуваної програми. Початкові тире теж повинні бути включені. Створює посилання на директиву option. якщо вона існує.
Наступна роль створює посилання на термін в словнику:
Якщо Ви використовуєте термін, який не має пояснення в словнику, то Ви Получется попередження при складанні.
Інша семантична разметка¶
Наступні ролі не роблять нічого особливого, крім форматування тексту в певному стилі:
Абревіатура. Якщо вміст ролі містить текст в дужках, то він буде розглянутий особливим чином: в HTML він буде показаний як підказка, і лише одного разу буде показаний в LaTeX.
Приклад:: abbr: `LIFO (last-in, first-out)`.
New in version 0.6.
Ім'я команди рівня OS, така як rm.
Позначає визначення в тексті. (Елемента індексу при цьому не створюється.)
Ім'я файлу або каталогу. У вмісті ролі Ви можете використовувати фігруние дужки для вказівки "мінливої" частини шляху, наприклад:
У готової документації x буде показаний зміненим чином, щоб позначити, що тут повинен знаходитися номер мінорній версії Python.
Мітки є частиною інтерактивного користувальницького інтерфейсу повинні бути позначені як guilabel. Це включає і мітки текстових інтерфейсів, таких, як створювані за допомогою curses або інших текстових бібліотек. Всі мітки, які використовуються в інтерфейсі повинні бути позначені цією роллю, включаючи мітки кнопок, заголовків вікон, назв полів, меню і навіть значень в списках вибору.
Changed in version 1.0: Клавіші швидкого доступу для GUI міток можуть бути додані за допомогою амперсанда; при виведенні він буде вилучений, а відповідна буква буде підкреслена (наприклад:: guilabel: `Cancel`). Для вставки самого амперсанда подвійте його.
Зазначає послідовність натискань клавіш. Форма цієї послідовності може залежати від платформи або програми. Якщо будь-яких домовленостей немає, то слід вказати повну назву клавіші-модифікатора, щоб допомогти новим користувачам і не носіям мови. Наприклад, послідовність клавіш для xemacs може бути позначена як: kbd: `C-x C-f`. але без посилання на конкретне застосування / платформу ту ж саму послідовність варто позначити як: kbd: `Control-x Control-f`.
Ім'я поштового заголовка в стилі RFC 822. Ця розмітка не означає, що заголовок використовується в поштовому повідомленні, але його можна використовувати для посилання на будь-який заголовок того ж самого "стилю". Він так само використовується для заголовків, які визначаються різними MIME специфікаціями. Ім'я заголовка має бути введено так само, як якщо б воно використовувалося в справі з переважним використанням CamelCase (where there is more than one common usage). Наприклад:: mailheader: `Content-Type`.
Ім'я змінних команди make.
Вибори меню повинні бути позначені за допомогою ролі menuselection. Вона використовується для позначки повної послідовності виборів меню, підміню і конкретних операцій. Або будь-яких послідовностей цих послідовностей. Імена окремих виборів повинні бути розділені за допомогою ->.
Наприклад, для оцінки вибору "Start> Programs", використовуйте наступну розмітку:
Якщо Ви включаєте вибори, які містять якісь індикатори в кінці імені, як, наприклад, три крапки, яке на деяких системах означає, що даний пункт меню відкриває діалог, ці індикатори повинні побут опущені.
menuselection так само підтримує використання амперсанда, як і guilabel.
Ім'я MIME типу, або компонента MIME типу (старшої або молодшої частини окремо).
Ім'я Usenet newsgroup.
Ім'я виконуваної програми. Може відрізнятися від імені файлу на деяких платформах. Зокрема, на Windows може бути опущено розширення .exe (або інше).
Регулярний вираз. Лапки вимикати не треба.
Шматок тексту або коду. У вмісті можна використовувати фігурні дужки для позначення "змінною" частини, як в file. Наприклад, в: samp: `print 1 +`. частина variable буде виділена.
Якщо Вам не потрібно позначати "змінну частину", тоді використовуйте станданий `` code``.
Крім того, є роль index для створення елементів індексу.
Наступні ролі створюють внешіне посилання:
Зверніть увагу, що немає ніяких спеціальних ролей для додавання гіперпосилань, так як для цього можна використовувати стандартну розмітку reST.
Подстановкі¶
Система документації надає три підстановки, які визначені за замовчуванням. Вони задаються в файлі конфігурації "збирача".
Замінюється релізом проекту, який описується в документації. Це повинна бути рядок з повною версією, включаючи теги alpha / beta / release / candidate, наприклад, 2.5.2b3. Задається: confval: `release`.
Замінюється версією проекту, який описується в документації. Це повинна бути рядок тільки з мажорним і мінорним номером версії, наприклад, 2.5 навіть для версії 2.5.1. Задається: confval: `version`.