“Hello world”拡張の開発¶
このチュートリアルの目標は、新しい指示を追加する非常に基本的な拡張を作成することです。この命令は“hello world”を含むパラグラフを出力する.
このチュートリアルでは基本情報のみを提供します。詳細についてはご参照ください other tutorials より多くの詳細を見ることができます
警告
この拡張については、以下のことについて基本的に理解する必要があります docutils ニシキヘビもいます
前提条件.¶
このプラグインは以下のように配布しません PyPI 既存のプロジェクトの一部としていますこれは、既存のプロジェクトを使用したり、新しいプロジェクトを作成する必要があることを意味します。 sphinx-quickstart それがそうです。
私たちはあなたが単独のソースを使用していると仮定します (source )と構築 (build )フォルダ。あなたの拡張ファイルはプロジェクトの任意のフォルダに配置することができます。私たちの例では、以下の操作を実行しましょう。
1つを作ることができます
_ext挟まれているsource新しいPythonファイルを作成します
_ext名前のフォルダhelloworld.py
以下は、入手可能なフォルダ構造の例です。
└── source
├── _ext
│ └── helloworld.py
├── _static
├── conf.py
├── somefolder
├── index.rst
├── somefile.rst
└── someotherfile.rst
拡張を作成しています¶
開いている. helloworld.py その中に以下のコードを貼り付けます
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | from docutils import nodes
from docutils.parsers.rst import Directive
class HelloWorld(Directive):
def run(self):
paragraph_node = nodes.paragraph(text='Hello World!')
return [paragraph_node]
def setup(app):
app.add_directive("helloworld", HelloWorld)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
|
この例ではいくつかの重要なことがあって、あなたはすべての指示でそれらを見るだろう。
指令類.
私たちの新しい指示は HelloWorld 級友たち。
1 2 3 4 5 | class HelloWorld(Directive):
def run(self):
paragraph_node = nodes.paragraph(text='Hello World!')
return [paragraph_node]
|
このような拡張はdocutils‘を拡張している. Directive 級友たち。作成されたすべての指示の拡張はこのクラスを拡張しなければならない。
これには1つの run 方法です。この方法は必要であり、すべての指示の一部でもある。これは命令の主な論理を含み，Sphinxで処理するdocutilsノードリストを返す.これらのノードはDocutilが文書の内容を表す方式である.多くのタイプのノードが利用可能である：テキスト、段落、引用、表など。
♪the nodes.paragraph クラスは新しいパラグラフノードを作成します。パラグラフノードには通常いくつかのテキストが含まれており，インスタンス化の過程で使用することができる. text パラメータ
♪the setup 機能
この機能は必要である.私たちはそれを使って私たちの新しい指示をSphinxに挿入した。
1 2 3 4 5 6 7 8 | def setup(app):
app.add_directive("helloworld", HelloWorld)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
|
あなたができる最も簡単なことは add_directive() 方法、これが私たちがここでやっていることです。この特定の呼び出しに対して、第1のパラメータは、RESTファイルで使用されるコマンド自体の名前である。この場合私たちは helloworld それがそうです。例：
Some intro text here...
.. helloworld::
Some more text here...
私たちはまた戻ります extension metadata これは，我々の拡張バージョンと，その拡張を並列読み出しと書き込みに用いることが安全であることを示している.
拡張モジュールの使用¶
拡張子はあなたの conf.py 文書は、スフィンクスにこれを認識させた。ここには2つのステップが必要です
追加
_extディレクトリをコピーして Python path Vbl.使用sys.path.appendそれがそうです。これはファイルの上部に置かれなければならない。更新または作成
extensionsリストを作成し、拡張ファイル名をリストに追加します。
例：
import os
import sys
sys.path.append(os.path.abspath("./_ext"))
extensions = ['helloworld']
ちなみに
私たちはこの拡張を Python package 修正する必要があります Python path これでスフィンクスは私たちの内線を見つけることができます。それが私たちが呼びかけなければならない理由です sys.path.append それがそうです。
今、この拡張子をファイルで使用することができます。例：
Some intro text here...
.. helloworld::
Some more text here...
上記の例は、以下のように生成される。
Some intro text here...
Hello World!
Some more text here...