第10日目 Sphinxドキュメントを編集する その７
昨日は toctree ディレクティブを使用してSphinxドキュメントを ツリー構造化 する方法を説明しました。
今日からドキュメントのネットワーク構造(リンクの張り方)の説明をします。
外部URLへのリンク
一番単純なURLへのリンクの張り方は、単にURLを記述する事です。
記述例:
http://sphinx-users.jp/
このように表示されます。
URLを見せずに文字列を見せたい場合は下記のように記述します。
記述例:
`sphinx <http://sphinx-users.jp/>`_
このように表示されます。
もし、同じリンクを使いまわしたい時は、
まず ターゲット定義 を書く:
.. _`sphinx`: http://sphinx-users.jp/
記述例:
この `sphinx`_ を会得すると、身も心も `sphinx`_ 化してしまい、 どんなドキュメントも `sphinx`_ にしないと気が済まなくなるらしい。
このように表示されます。
明日はSphinxドキュメント内へのリンクを説明します。
※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。
第9日目 Sphinxドキュメントを編集する その６
昨日までに、基本的な reStructuredText を説明しましたので index.rst 1つなら十分編集する事が出来るようになったと思います。
今日から、複数のファイルを作成しSphinxでドキュメントを構造化する方法を説明します。
まずはドキュメントを構造化する際に骨となる toctree ディレクティブの説明です。 とても重要なディレクティブですので必ず読んで下さい。
ドキュメントを構造化する
ドキュメントを作成する際は、大抵、大項目をいくつか挙げ、その下に紐付く中項目、小項目をぶら下げる ツリー構造 で考える事が多いのではないでしょうか？ ツリー構造 であれば見通しがよくなりドキュメントの作成を進めやすいですよね。
Sphinxの場合は ツリー構造 にする方法が2つあります。
1. toctree ディレクティブ
index.rst と同じディレクトリ階層に2つのreSTファイルを置くと仮定します。
first.rst:
1つ目のファイル ================ * これは1つ目のファイルです。
second.rst:
2つ目のファイル ================ * これは2つ目のファイルです。
これらのファイルを index.rst に読み込ませるには下記のように記述します。
.. toctree:: first second
html化すると このようになるはずです。
2. ディレクトリ管理
単純にreSTファイルをディレクトリに小分けして格納するだけです。
.. toctree:: unyo/tejun01 unyo/tejun02 unyo/tejun03 kochiku/network kochiku/kanshi kochiku/server
例では index.rst と同じ階層に unyo , kochiku というディレクトリを作成し、それぞれのディレクトリ配下にreSTファイルを作成してあります。
- unyoディレクトリ
- tejun01.rst
- tejun02.rst
- tejun03.rst
- kochikuディレクトリ
- network.rst
- kanshi.rst
- server.rst
※例は省きます
- unyoディレクトリ
明日はネットワーク構造(リンクの張り方)の説明をします。
※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。