Jaderné noviny - 14. 7. 2016: Dokumentace jádra ve Sphinx a jak funguje, část 2.

24. 7. 2016 | Redakce | Jaderné noviny | 2196×

Stav vydání jádra. Dokumentace jádra ve Sphinx a jak to funguje, část 2.

Stav vývoje jádra

Současný vývojový kernel je 4.7-rc7, který byl Linusem vydán 10. července. „Každopádně ještě zbývá několik regresí, které se řeší, ale pokud se nestane nic divného, jde o poslední rc. Nicméně vzhledem ke svému cestovnímu plánu nevydám poslední 4.7 příští víkend a lidé budou mít dva týdny času k nahlášení (a opravě) zbývajících chyb. Takhle to bude. Můj cestovní plán nic nenabourává, místo toho ho berte tak, že dostáváte týden času navíc! Hurá!“

Thorsten Leemhuis 10. července vydal další revizi seznamu regresí pro 4.7. Celkem je jich tam deset, z toho dvě jsou nové.

Stabilní aktualizace: 4.6.4 a 4.4.15 byly vydány 11. července.

Dokumentace jádra ve Sphinx, část druhá: Jak to funguje

Strom dokumentace jádra prochází zásadním přerodem směřujícím k používání Sphinx a reStructedText k vytváření formátovaných dokumentů. První článek v tomto krátkém seriálu se věnoval tomu, jakými rozhodnutími si prošla vývojářská komunita, než padla volba na Sphinx. Tento závěrečný článek se věnuje mechanismům nového dokumentačního systému a tomu, jak je rozšiřovat.

Z pohledu příležitostného vývojáře se proces sestavování dokumentace příliš nezměnil. Od jádra 4.8 spustí obvyklé příkazy make htmldocs a make pdfdocs jak Sphinx k sestavení dokumentace v reStructuredTextu, tak starou sadu nástrojů, která sestavuje dosavadní dokumentaci v DocBooku. Bude samozřejmě zapotřebí mít nainstalovaný Sphinx. Pro hezčí HTML se bude používat motiv vzhledu Sphinx Read the Docs (sphinx_rtd_theme) – bude-li k dispozici. Pro výstup do PDF je zapotřebí balíček rst2pdf. To vše je k dispozici ve stabilních distribucích.

Sestavení dokumentace pomocí Sphinx probíhá pomocí vyhrazeného souboru Documentation/Makefile.sphinx, konfigurace je v souboru Documentation/conf.py. Generované soubory jsou umístěny pod Documentation/output v podadresářích odpovídajících formátu. V reStructuredTextu zatím moc dokumentace napsáno není, ale dokumentace grafického subsystému, jakožto i dokumentace týkající se nasazení Sphinx bude včas připravena do vydání 4.8. V plánu je zkonvertovat všechny dokumenty využívající DocBook do formátu reStructuredText a s DocBookem se konečně rozloučit.

Z hlediska systému, který se stará o sestavení dokumentace, je Sphinx ve srovnání se sadou nástrojů kolem DocBooku příjemně jednoduchý. Sám zvládá závislosti mezi dokumenty, příslušná data uchovává ve výstupním adresáři. To umožňuje sestavení, aniž by příslušné nástroje věděly, který soubor se překládá na který.

Psaní dokumentace

Dopisování dokumentace může se Sphinx být velmi jednoduché, stačí následovat těchto pár kroků:

1. Přidáme nový soubor ve formátu reStructuredText – s příponou .rst – někam do Documentation.
2. Odkážeme se na něj z hlavního rejstříku Documentation/index.rst.

Zatím se spíš budou stávající soubory (v prostém textu či DocBooku) konvertovat na reStructuredText, než že by se přidávaly soubory nové. Protože zatím soubory s prostým textem nepoužívaly žádnou konzistentní syntaxi, je nutné je konvertovat manuálně. Naštěstí ale formátování v prostém textu obvykle nemá daleko k syntaxi nějakého toho jednoduchého značkovacího jazyka. Očekáváme, že časem budou některé z těch tisíců stávajících souborů v prostém textu přepsány do reStructuredTextu, ovšem není žádný spěch a ne všechno musí být součástí sestavení dokumentace.

Konverze z DocBooku je mnohem zajímavější. K dispozici je „prachbídný konverzní skript“ od Jonathana Corbeta; nachází se v Documentation/sphinx/tmplcvt a využívá pandoc spolu s nějakými zásahy sedem před zpracováním a po něm. Markus Heiser pracuje na několika pokročilejších skriptech. Šablony DocBooku by si primárně měli převést sami jejich autoři nebo správci, aby se ujistili, že vše bude v pořádku a v při konverzi se do obsahu nezanesou žádné chyby. Konverze je každopádně jednorázová záležitost, takže časem bude vylepšování skriptů zbytečné. (Zde je ukázka některých souborů konvertovaných z DocBooku Corbetovým mizerným skriptem, a to bez dodatečné ruční editace.)

Po konverzi se šablony DocBooku spolu s další dokumentací umístí do Documentation místo do Documentation/DocBook. Tento adresář je totiž spolu s celou sadou nástrojů DocBooku odsouzen k odstranění, až budou všechny dokumenty převedeny do nového formátu. Těžit by z toho mohli i vývojáři, které generování hezkých dokumentů z šablon DocBooku do reStructuredTextu vůbec nezajímá, protože grepování a čtení souborů ve formátu reStructuredText je mnohem snazší než v případě bince plného špičatých závorek v DocBooku.

Příležitostně bude zapotřebí propracovanější organizace než jen cpaní všeho do hlavního rejstříku. Zvláště výstupy do PDF je třeba rozdělit na několik dokumentů. S přibývajícími dokumenty to půjde udělat skrze nastavení v Documentation/conf.py. Pro začátek to však vypadá, že přímočarost je ten správný způsob, jak na to.

Formátované komentáře kernel-doc

Při sestavování dokumentace pomocí Sphinx se nově komentáře kernel-doc berou jako reStructuredText. Nějaké problémy se vzhledem k tomu, že komentáře nebyly psány s ohledem na reStructuredText, jistě objeví, ale většinou to prostě funguje.

Skript kernel-doc zpracovává formátované vysokoúrovňové komentáře (jména funkcí a struktur, parametry, popisy členských proměnných atd.); generuje pro ně vhodné kotvy z domény C Sphinx; filtruje komentáře ke zvýraznění a křížové odkazy; zbytek propouští tak, jak je. Filtry mimo jiné konvertují function_name() a odkazy na typy struktur (za použití konvence &struct struct_name) na řádné křížové odkazy z domény C.

Vyhrazené rozšíření Sphinx začleňuje komentáře kernel-doc ze souborů se zdrojovými kódy do dokumentu. Vnitřně toto rozšíření volá kernel-doc, aby požadavek provedl, a informuje Sphinx o závislostech dokumentu na souborech se zdrojovými kódy. Rozšíření umožňuje zahrnout komentáře kernel-doc do libovolného souboru v Documentation, formátovaného reStructuredTextem, aniž by bylo nutná jakákoliv zvláštní obsluha nebo sledování závislostí v předpisech pro sestavení.

Například pro zahrnutí dokumentace všech funkcí exportovaných pomocí EXPORT_SYMBOL() z bitmap.c bychom napsali následující:

    .. kernel-doc:: lib/bitmap.c
       :export:

Pro přehled sekce dokumentace z intel_audio.c:

    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
       :doc: High Definition Audio over HDMI and Display Port

Titulek za DOC: uvedený ve zdrojovém kódu se chová jako identifikátor sekce. Také je možné zahrnout dokumentaci specifických typů nebo funkcí.

Příspěvky Daniela Vettera umožňují rozšíření kernel-doc krmit Sphinx souborem se zdrojovým kódem a čísly řádků dílčích dokumentačních komentářů, aby se zlepšily diagnostické zprávy v chybách reStructuredTextu. To se bude hodit při napravování chybiček zmíněných výše.

Budoucí práce

Mluvilo se (a Markus dokonce ukázal kód) o konverzi skriptu kernel-doc z Perlu do Pythonu a jeho možném spuštění přímo v rozšíření Sphinx. Není však jasné, zda se vyplatí jen tak mezi jazyky přepisovat vlastní analyzátor C, který je již prověřený časem – dvěma dekádami nasazení v praxi. Možná, že lepší nápad by byl zásuvný modul překladače.

Jak jsme psali dříve, zvláště dokumentace médií si žádá lepší syntaxi pro tabulky. Za tímto účelem sepsal Markus rozšíření pro Sphinx, které podporuje krom jiného slévání řádků a sloupců v tabulkách. I toto rozšíření je zřejmě připraveno k začlenění do vydání 4.8; jedná se o závislost k převádění dokumentace médií.

Pozitivní je, že většina zde popisované práce již byla začleněna. Budeme svědky nárůstu objemu patchů týkajících se převodu dokumentace reStructuredTextu, jakož i oprav a vylepšování komentářů kernel-doc ve zdrojových kódech. Doufejme, že změny zlepší stav dokumentace jádra jako celku a o krok nás posunou k vizi správce dokumentace, jak ji vyjádřil v prezentaci na linux.conf.au: „Pokud to uděláme, za několik let budeme mít krásný integrovaný dokumentační strom, který pokrývá věci komplexním způsobem, kde najdete to, co hledáte, a který ještě ke všemu vypadá hezky. Je to hezká vize, když na ni myslím, slyším zpěv andělů a tak vůbec. To je směr, kterým se chci ubírat.“

Jani Nikula je zaměstnancem Intelu, pracuje na grafickém subsystému Linuxu a je také autorem většiny prací týkajících se Sphinx, s přispěním Daniela Vettera a Jonathana Corbeta.

       

Diskuse k tomuto článku