Sfinxul folosește roluri de text interpretate pentru a insera marcarea semantică în documente. Acestea sunt descrise ca: rolename: `content`.
Rolul implicit ("conținut") implicit nu are niciun sens special. O puteți folosi pentru orice. Utilizați valoarea de configurare: confval: `default_role` pentru a lega acest lucru într-un rol cunoscut.
Vedeți domenii. unde este descrisă adăugarea de roluri către domenii.
Sintaxa referințelor încrucișate¶
Există câteva caracteristici suplimentare care fac trimiterile mai flexibile:
. textul legăturii va fi doar ultima componentă a obiectivului. De exemplu,: py: meth: `
Queue.Queue.get` se va referi la Queue.Queue.get, dar numai obține va fi afișat ca text.
În ieșirea HTML, atributul link-ului de titlu (ceea ce se afișează când treceți peste un link) va fi întotdeauna numele complet al destinației.
Obiecte de referință
Următoarele roluri sunt descrise în domeniile corespunzătoare:
Orice poziționare a referințelor transversale¶
Pentru a oferi posibilitatea de a se referi la locurile arbitrare din orice document, se utilizează etichetele standard (etichete) reST. Pentru ca aceste nume de etichete să funcționeze, acestea trebuie să fie unice în întreaga documentație. Există două moduri în care vă puteți referi la etichete:
Dacă plasați o etichetă chiar înaintea antetului secțiunii, puteți să o trimiteți folosind: ref: `label-name`. De exemplu:
Etichetele automate funcționează, de asemenea, cu cifre:
În acest caz: ref: `my-figure` va introduce un link la cifra cu textul link-ului 'Forma de titlu'.
Același lucru funcționează pentru tabelele cu antetul specificat, pentru care trebuie să utilizați directiva: dudir: `table`.
Etichetele care nu sunt localizate înainte de titlul unei secțiuni pot fi totuși folosite pentru referințe, dar în acest caz trebuie să specificați un antet pentru link utilizând următoarea sintaxă :: ref: `Titlu link
Utilizarea ref preferat peste referințele standard pe secțiunea reStructuredText (de exemplu, secțiunea `title`_), ca prima metodă va funcționa în cazul unei secțiuni antet modificări și funcționează pentru toate„culegătorii“care sprijină eco-referință.
Referințe încrucișate la documente¶
Nou în versiunea 0.6.
În plus față de toate cele de mai sus, există o modalitate de a se referi direct la documente:
Dacă textul link-ului nu este specificat (spre deosebire de :: doc: Monty Python members `), atunci titlul documentului va fi folosit ca acesta.
Descărcați link-uri¶
Nou în versiunea 0.6.
Acest rol vă permite să vă referiți la fișiere care nu sunt documente reST și care pot fi descărcate.
Când utilizați acest rol, fișierul referit este marcat automat pentru includerea în ieșire în timpul asamblării (evident, acest lucru este valabil numai pentru ieșirea HTML). Toate fișierele descărcate sunt plasate în subdirectorul _downloads al directorului de ieșire; nume de fișiere duplicat sunt tratate.
Numele fișierului este de obicei specificat în raport cu fișierul care conține această directivă; dar dacă este specificată în formă absolută (începând cu /), atunci este considerată relativă la directorul cu fișierele sursă.
Referințe încrucișate la alte elemente¶
Următoarele roluri vă permit să creați referințe încrucișate, dar nu se referă la obiecte specifice:
Numele jetonului gramatical (simbol gramaticar) (folosit pentru a crea legături între directivele de producție).
Numele cuvântului cheie Python. Creează o referință la eticheta menționată cu acest nume, dacă există.
Opțiunea de linie de comandă pentru programul executabil. Trebuie incluse și liniile inițiale. Creează o referință la directiva privind opțiunile. dacă există.
Următorul rol creează o referință la termen în dicționar:
Dacă utilizați un termen care nu are nicio explicație în dicționar, veți primi un avertisment la asamblare.
Alte marcări semantice
Următoarele roluri nu fac nimic special, cu excepția formatării textului într-un anumit stil:
Abreviere. Dacă conținutul rolurilor conține textul în paranteze, acesta va fi tratat într-un mod special: în HTML acesta va fi afișat ca o sugestie și o singură dată va fi afișat în LaTeX.
Exemplu :: abbr: `LIFO (last-in, first-out)`.
Nou în versiunea 0.6.
Numele comenzii de nivel OS, cum ar fi rm.
Marchează definiția din text. (În acest caz, nu este creat un element index.)
Numele fișierului sau al directorului. În conținutul rolului, puteți utiliza parantezele pentru a indica partea "variabilă" a căii, de exemplu:
În documentația finalizată, x va fi arătată într-o manieră modificată pentru a indica faptul că ar trebui să existe o versiune minoră a Python.
Etichetele care fac parte din interfața interactivă a utilizatorului trebuie să fie etichetate ca guilabel. Acestea includ etichete pentru interfețe text, cum ar fi cele create cu curse sau alte biblioteci de text. Toate etichetele utilizate în interfață trebuie să fie etichetate cu acest rol, inclusiv etichetele butoanelor, titlurile ferestrelor, numele câmpurilor, meniurile și chiar valorile din listele de selecție.
Modificat în versiunea 1.0: tastele de comenzi rapide pentru etichetele GUI pot fi adăugate utilizând o ampersand; când este eliminat, va fi șters și litera corespunzătoare va fi subliniată (de exemplu: guilabel: "Anulare"). Pentru a introduce ampersand-ul însuși, dublați-l.
Indică succesiunea intrărilor de taste. Forma acestei secvențe poate depinde de platformă sau de aplicație. Dacă nu există acorduri, trebuie să specificați numele complet al cheii de modificare pentru a ajuta utilizatorii noi și vorbitorii non-nativi. De exemplu, secvența cheie pentru xemacs poate fi notată ca: kbd: `C-x C-f`. dar fără referința la o aplicație / platformă specifică, aceeași secvență ar trebui desemnată ca: kbd: Control-x Control-f.
Numele titlul e-mailului în stilul RFC 822. Acest marcaj nu implică faptul că titlul este utilizat într-un mesaj, dar poate fi folosit pentru a desemna orice antet de același „stil“. Este de asemenea utilizat pentru anteturi definite de diferite specificații MIME. Numele antet ar trebui să fie introduse în același mod ca și în cazul în care a fost utilizat într-o CamelCase utilizare preferată (în cazul în care există mai mult de o utilizare comună). De exemplu:: mailheader: "Content-Type".
Numele variabilelor pentru marcă.
Selecțiile de meniuri trebuie să fie marcate utilizând rolul de selectare a meniurilor. Este folosit pentru a marca secvența completă a opțiunilor, submeniurilor și operațiilor specifice ale meniului. Sau orice secvență a acestor secvențe. Numele alegerilor individuale ar trebui separate prin ->.
De exemplu, pentru a marca selecția "Start> Programe", utilizați următoarea marcare:
Dacă activați alegerile, care conțin unii indicatori la sfârșitul numelui, cum ar fi puncte, care, în unele sisteme, înseamnă că elementul de meniu se deschide un dialog, acești indicatori ar trebui să fie lăsat în afara vieții.
menuselection sprijină, de asemenea, utilizarea de ampersands, cum ar fi guilabel.
Numele tipului MIME sau al componentei MIME de tip (ridicat sau scăzut).
Numele grupului de știri Usenet.
Numele programului executabil. Este posibil să difere de numele fișierului pe unele platforme. În special, extensia .exe (sau alta) poate fi omisă pe Windows.
Expresie regulată. Nu rotiți ghilimelele.
O bucată de text sau de cod. Aveți posibilitatea să utilizați acolade în coșul de conținut pentru a semnifica partea "variabilă", ca în fișier. De exemplu, în: samp: `print 1 +`. o parte a variabilei va fi evidențiată.
Dacă nu este necesar să desemnați partea "modificabilă", atunci folosiți codul standard ``.
În plus, există un rol index pentru crearea elementelor index.
Următoarele roluri creează text suplimentar:
Rețineți că nu există roluri speciale pentru adăugarea de hyperlink-uri, deoarece puteți utiliza marcajul standard reST pentru aceasta.
Substituții Sub
Sistemul de documentare oferă trei înlocuiri care sunt definite în mod implicit. Acestea sunt specificate în fișierul de configurare al "colectorului".
Înlocuit cu lansarea proiectului, care este descris în documentație. Ar trebui să fie un șir cu versiunea completă, inclusiv etichetele alfa / beta / release / candidate, de exemplu, 2.5.2b3. Specifică: confval: `release '.
Înlocuit cu versiunea proiectului, care este descrisă în documentație. Acesta ar trebui să fie un șir cu doar un număr de versiune majoră și minoră, de exemplu 2,5, chiar și pentru versiunea 2.5.1. Specifică: confval: `version`.
Trimiteți-le prietenilor: