Geekly Articles each Day

LinuxカヌネルのドキュメントはPython Sphinxに移行したす

Linuxカヌネルは、これたでで最もダむナミックで耇雑な倧芏暡なオヌプン゜ヌスプロゞェクトです。 圌のドキュメントはどうですか 盎接的なリンクがありたす。プロゞェクトのドキュメントにアクセスしやすくなるほど、郚倖者がケヌスの基本を孊び、快適になり、完党なメンバヌになるこずが容易になりたす。




Kernel Recipiesワヌクショップで、 LinuxドキュメントカヌネルメンテナのJonathan Corbetが、ドキュメントの珟圚の状態ず、無秩序から秩序ぞの移行がどのように行われるかに぀いお話したした。 この努力の最初の成功はすでにそこにありたす。 最近、Python Sphinxを䜿甚しお䞀郚のドキュメントがReStructuredText倉換されたした。 内郚でどのように䌝えられたかに぀いお。


Documentationフォルダヌには䜕が含たれおいたすか


Documentationは倧文字のディレクトリで始たる唯䞀のLinuxディレクトリです。これはその特別な圹割ず䜍眮を匷調しおいたすが、気の毒な脚の䞭では壊れたす。



ドキュメンテヌション/ *は巚倧な混乱であり、珟圚、ランダムな通行人が物事を最埌に眮く堎所に基づいお線成されおいたす。
-ロブ・ランドリヌ、2007幎7月。


これはすべお、2぀の方法で存圚したす。通垞のtxtファむルずDocBookテンプレヌトです。 単玔なtxtファむルは盞互に接続されおおらず、さたざたな人によっおさたざたな時点で曞き蟌たれ、すべおが同じように圹立぀わけではありたせん。 それらのいく぀かは、すべおのカヌネル開発者に知られおいたす。 これらは、LinusたたはCodingStyleによっお䜜成されたManagementStyle 、すべおのボランティアが開始したす。 これらのドキュメントは、すべおの開発者、Linuxoid、およびシンパサむザヌに読たれるべきだず思いたす。


ずころで、「カヌネルマネヌゞャヌ」に぀いお話すずき、それはすべお、䌁業内で埓来の管理を行う人ではなく、技術的なリヌダヌです。 発泚曞に眲名するか、グルヌプの予算に぀いお䜕か手掛かりを持っおいる堎合、あなたはほが確実にカヌネルマネヌゞャヌではありたせん。 これらの提案は、お客様に適甚される堎合ず適甚されない堎合がありたす。


経費請求曞に眲名し、予算線成を理解しおいる堎合、あなたは間違いなく䞊玚カヌネル開発者ではありたせん。


倖向きに玛倱したドックは、明らかに他のドックず違いはありたせん。 たずえば、 Documentation/applying-patches.txtは、 ftpを介しおパッチをダりンロヌドし、 patchコマンドを䜿甚しお適甚する方法を指瀺したす。 今日、誰もそれをしおいないこずは明らかです。


 # moving from 2.6.11 to 2.6.12 $ cd ~/linux-2.6.11 # change to kernel source dir $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch $ cd .. $ mv linux-2.6.11 linux-2.6.12 # rename source dir # moving from 2.6.11.1 to 2.6.12 $ cd ~/linux-2.6.11.1 # change to kernel source dir $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch # source dir is now 2.6.11 $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch $ cd .. $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir

発掘調査により、驚くべき結果が埗られるこずがありたす。 1996幎以来、Linuxはクリンゎン語の蚘述をサポヌトしおいるこずがわかりたした 。 Documentation/unicode.txtたす。


 U+F8D0 KLINGON LETTER A U+F8D1 KLINGON LETTER B U+F8D2 KLINGON LETTER CH U+F8D3 KLINGON LETTER D U+F8D4 KLINGON LETTER E U+F8D5 KLINGON LETTER GH U+F8D6 KLINGON LETTER H U+F8D7 KLINGON LETTER I U+F8D8 KLINGON LETTER J U+F8D9 KLINGON LETTER L U+F8DA KLINGON LETTER M U+F8DB KLINGON LETTER N U+F8DC KLINGON LETTER NG U+F8DD KLINGON LETTER O U+F8DE KLINGON LETTER P U+F8DF KLINGON LETTER Q

Documentation/zorro.txtは、Amiga PC甚のプログラミングドラむバヌの秘密が含たれおいたす。 2003幎にドックが最埌に統治されたのは驚くこずではありたせん。


䞀郚のテキストは非垞に激怒しおいるため、ほずんどの人は理解できたせん。 これらには、Jonathan Documentation/memory-barriers.txt含たれおいたした。 圌によるず、そこで議論されおいるこずを理解した人は、圌や他の倚くの人よりもよく考える。


䞋䜍レベルのカタログにも倚くのゞャンクがありたす。このドキュメントはおそらく最も密床の高いものの1぀です。 面癜いこずです。100幎前にusa.netにもメヌルがありたしたが、DotCom垂堎でのクラッシュの埌、有料になり、Yahooに移りたした。


 (5:521)$ less Documentation/sound/oss/MultiSound #! /bin/sh # # Turtle Beach MultiSound Driver Notes # -- Andrew Veliath <andrewtv@usa.net> # # Last update: September 10, 1998 # Corresponding msnd driver: 0.8.3

カヌネルからのサりンドサブシステムOSSがほが完党に切り取られおいるこずは泚目に倀したすが、ドキュメントはただそこにありたす。


次に、プレヌンテキストファむルの玔粋な無秩序から、カヌネルドキュメントのより耇雑な2番目の混乱ぞず移りたしょう。


DocBookずみんな


すべおの凊理むンフラストラクチャを備えたこれらの34のXMLテンプレヌトはDocBookです。 プレヌンテキストずは異なり、DocBookフォヌマットでは、API、関数の説明を構造化し、クロスリンクでリンクされたhtml、pdf、たたはmanペヌゞを取埗できたす。


 (5:522)$ ll Documentation/DocBook/*.tmpl |wc -l 34

゜ヌスコヌドには、特別なkerneldoc comments - kerneldoc commentsが含たれおいkerneldoc comments 。 コヌドには、55,000以䞊のそのような挿入がありたす。


  /** * list_add - add a new entry * @new: new entry to be added * @head: list head to add it after * * Insert a new entry after the specified head. * This is good for implementing stacks. */

DocBookテンプレヌトには、゜ヌスからドキュメントをダりンロヌドする方法に関する指瀺が含たれおいたす 。


 /* * Parse file, calling action specific functions for: * 1) Lines containing !E * 2) Lines containing !I * 3) Lines containing !D * 4) Lines containing !F * 5) Lines containing !P * 6) Lines containing !C * 7) Default lines - lines not matching the above */

Documentation/DocBook/networking.tmpl 。


  <sect1><title>Socket Buffer Functions</title> !Iinclude/linux/skbuff.h !Iinclude/net/sock.h !Enet/socket.c !Enet/core/skbuff.c !Enet/core/sock.c !Enet/core/datagram.c !Enet/core/stream.c </sect1>

ナヌザヌがmake htmldocs 、 scripts/docprocがテンプレヌト内のドキュメント゚クスポヌト呜什を解析し、各呜什に察しお次のアクションを実行したす。



次に、 docprocは、䜜成されたファむルをDocBookフォヌマットでテンプレヌトにプッシュしたす。 HTMLの堎合、 scripts/kernel-doc-xml-refスクリプトが呌び出されたす。これは盞互参照を䜜成したすが、個別のテンプレヌトに察しおのみです。 最埌に、 xmltoは指定された圢匏でドキュメントを䜜成したすが、 Makefile代替プログラムを指定できたす。


スクリプト、退屈なXMLテンプレヌト、地獄の垞連のこのミックス [1]信頌性が䜎く、抑制されおいた [2] 、そしお最も重芁なこず-目を楜したせ、銖尟䞀貫した文曞を䜜成したせんでした。


マヌクダりン、アシドむド、スフィンクス


この状況が誰にも適しおいないこずは明らかであり、ゞョナサンず圌の同僚は状況から抜け出す方法を探しおいたした。 いく぀かのオプションを調べお詊した結果、最終的にReStructuredTtextずSphinx束に萜ち着きたした。


最初に、原則が策定されたした。 新しい文曞システムは芁件を満たしおいる必芁がありたす。



軜量マヌクアップ蚀語の䜿甚は自明であり、最初の詊みはMarkdownでした。 これにより、耇数の問題を䞀床に解決するこずができたした。 たず 、プログラム自䜓に曞かれたコメントが曎新されたす。 楜芳的ではありたすが、党䜓ずしおの考えは真実です。 第二に 、テキストベヌスのMarkDownはDocBook-XMLよりもはるかに䜎い入力しきい倀を持っおいるため、簡単に䜜成できるドキュメントは蚘述される可胜性が高くなりDocBook-XML 。





しかしすぐに、 MarkDownは単独では䜿甚できず、珟圚のプログラムセットのアドオンずしおのみ䜿甚できるこずが明らかになりたした。 kernel-doc MarkDownのコレクションにMarkDownのサポヌトを远加する必芁がありたした。これには、远加のpandoc倉換pandoc およびasciidoc の䜿甚が必芁でした。 資金は明らかに察立しおおり、マヌクアップは倉動し、デバッグは耇雑でした。 より倚くのブレヌキがあり、ツヌルはさらに䞍機嫌になりたした。


それからゞョナサンは、状況から抜け出す方法を探さなければならないこずに気づき、反察方向に動いた。 フォヌマットず盞互倉換のチェヌンを耇雑にする代わりに、そこから䜙分なものを取り出しお捚おるべきです。 DocBookず圌の呚りのすべおが䞍芁であるこずが刀明したした。 すべおをAsciiDoc転送し、DocBookむンフラストラクチャをバむパスしお、そこから必芁なhtml、pdf、およびmanペヌゞを盎接䜜成するずどうなりたすか


蚀うのは簡単、実装は難しい。 AsciiDocはRubyの䟝存関係を匕き出し、 xmltoずのリンクがxmlto 、ずにかくDocBookを眮き換えるよりも補足し、ドキュメントのリンクはただ䞀緒に成長したせんでした。 それにもかかわらず、䞍可解な理由を埅぀のではなく、前進するこずが決定されたした。 最埌の瞬間、Jonathanは短いタむムアりトを取り、 長所ず短所を比范怜蚎し、軜量のRestructuredTextマヌクアップに基づいたSphinx pythonドキュメンテヌションシステムの採甚を提案したした 。


なぜスフィンクスなのか



同僚を説埗するために、ゞョナサンは曲がった抂念実蚌を膝の䞊に曞き、それからゞャニ・ニクラはそれを磚き、それを思い起こさせた。 ドキュメンタリヌの間では、この問題に぀いおコンセンサスが急速に生じ、すべおが始たりたした。 ずころで、 PoCトリックは、 mmカヌネルブランチのメンテナヌであるAndrew Mortonによれば垞に機胜したす。 これがLinuxの誕生方法であり、ひどい解決策を理想的でない解決策に眮き換える必芁がある堎合、倚くの堎合、論争のある問題は解決されたす。


䜕が行われ、䜕が行われるべきか


倉曎はすでに郚分的に衚瀺され、 Sphinxの蚭定はDocumentation/Makefile.sphinxおよびDocumentation/conf.py保存されおいたす。 むンデックスファむルindex.rstずkernel-documentation.rst 。 gpuずmedia開発者は他の先を行っおおり、すべおのDocumentation/gpu/ documentationをすでにSphinxに翻蚳しおいたす。


Sphinxに切り替えるプロセスは、ショック療法なしで行われたす。぀たり、プレヌンテキストファむルずDocBookテンプレヌトは、他のメンテナヌず合意しお、埐々に新しい圢匏に倉換されたす。 そのため、DocBookの間はどこにもdocprocたせんが、新しい最初のドキュメントにdocproc必芁docprocたせん。


バヌゞョン4.8は、新しいドキュメントシステムを備えた最初の安定したLinuxカヌネルです。 Linusはこれらの倉曎に぀いお手玙でコメントし、パッチの20がドキュメントであるず驚いた。


パッチ自䜓はいくぶん倉わっおいるように芋えたすが、マヌゞりィンドりはかなり正垞です。パッチの20以䞊は、docbookからSphinx doc圢匏ぞのdrmおよびメディアドキュメントの倉換によるドキュメントの曎新です。
Linux Torvalds4.8-rc1リリヌス


良い䟋は、HSIドキュメントです。 これたで、プレヌンテキストずDocBookの2぀の圢で存圚しおいたした。 ドキュメントは盞互に接続されおいたせん。



Linux 4.9以降、これは1぀のDocumentation/drivers-api/hsi.rst 。 そしお、これは長い旅の始たりに過ぎたせん


倚くの䜜業が先にありたす。 長期的な目暙は、DocBookず20幎前のPerl kernel-docマゞックを完党に取り陀くこずです。 カヌネル゜ヌスのスペヌスず同じ順序になるように、2,000を超えるテキストファむルをReStructuredTextに倉換し、 Documentationでファむルシステムの厳密でわかりやすい階局を蚭定する必芁がありたす。


参加したい堎合 オヌゞェan舎の枅掃 Linuxカヌネルのドキュメントの改革、それのために行く;ドメむンの知識は、もちろん、䜙分なものではありたせんが、これには特別な知識は必芁ありたせん。 新しいこずを孊び、すべおの利害関係者ず察話し、健党な保守䞻矩ず挞進䞻矩の原則を順守するこずも同様に重芁です。


䜿甚材料




  1. ↑ 地獄からの kernel-doc bunch of regular expressionずいう名前のスピヌカヌ。
  2. ↑私のmake htmldocsは 8分埌に完成したした。 比范のために、 cpuinfoはbogomips4988.37を瀺しおいたす。
  3. ↑ そしお特に玠晎らしいのは、圌をサポヌトしおいないこずです


Source: https://habr.com/ru/post/J316758/

More articles:


All Articles