第11日目 Sphinxドキュメントを編集する その８
昨日は外部リンクの張り方を説明しました。今日は プロジェクト 内へのリンクを説明します。
ドキュメントへのリンク
他のドキュメント( rstファイル )へリンクを張りたい時は :doc: というマークアップをします。
記述例:
昨日のタイトルは :doc:`../10/write_rest7` です。一昨日は :doc:`toctree <../09/write_rest6>` について説明しましたね。
このように表示されます。
昨日のタイトルは 第10日目 Sphinxドキュメントを編集する その７ です。一昨日は toctree について説明しましたね。
ファイルへのパスは拡張子が不要です。
ファイルパスはドキュメントの起点となる index.rst を / (ルート) とした絶対パスか、相対パスで記述して下さい。
セクションへのリンク
アンカーを設置する
セクション へリンクを張る為にはリンクを張りたい セクション にアンカーを配置する必要があります。
ノート
セクション は同じ プロジェクト 内であれば違う rstファイル であっても構いません。
記述例:
.. _schedule: タイトル(予定かつ順不同) -------------------------
アンカー自体は表示されません。
アンカーを配置したセクションへリンクする
:ref: でセクションへリンクします。
記述例:
このアドベントカレンダーについての :ref:`schedule` へジャンプしましょう。 :ref:`こういう書き方 <schedule>` もできますよ。
このように表示されます。
このアドベントカレンダーについての タイトル(予定かつ順不同) へジャンプしましょう。
こういう書き方 もできますよ。
ノート
アンカーは前に :: (セミコロン×2) と文字列の頭に _ (アンダーバー) が付いていますが :ref: で指定する際はどちらも外します。
明日は画像ファイルやダウンロードをさせるリンクを説明します。
※ このアドベントカレンダーについては このアドベントカレンダーについて を参照して下さい。
本家 Sphinx Advent Calendar 2012 10日目 ～サクラエディタから make html～
9日目の 波田野さん ( @tcsh )から受け取りました。
ドキュメント作成の歴史を紐解きながら、ドキュメントの構造化～システマティックなドキュメント作成への期待を語られていて興味深く感じました。
さて 本家 Sphinx Advent Calendar 2012 の10日目です。全部俺版とは別に投稿したいと思います。
サクラエディタとマクロ
最近では Vim や Sublime Text 2 、 Emacs だとかが流行っているらしいですが、Windows使ってるなら サクラエディタ でしょう。
仕事柄、色々な現場に入るのですが、どこでも サクラエディタ は必ず使われています。かくいう私も10年程 サクラエディタ を使っておりました。 第3日目 Sphinxドキュメントを書く道具 も参照して頂けると幸いです。
makeからブラウザ確認までを1動作で
- タイトルの通りです。サクラエディタで編集する際に 編集 -> make html -> ブラウザを起動して確認 ..... というサイクルの手間を少し省く事ができます。
使い方
これ をダウンロードし、任意のディレクトリに配置します。
例:
C:\tools\Editor\macro\build_and_browsing.vbs
設定 -> 共通設定 -> マクロ タブにて マクロ一覧 にマクロを配置したディレクトリを指定します。
マクロの登録一覧の空欄の部分を選択します。初めて登録するならば 0 を選択しましょう。
名前 に任意の名前を付けます。とりあえず make html としておきましょう。
File にてドロップダウンメニューからマクロのファイルを選択します。
設定 をクリックします。
マクロ一覧 の 0 に make html が登録された事を確認します。
キー割り当て タブをクリックします。
種別 を 外部マクロ にします。
make html をクリックします。
任意のキーを割付して下さい。
例 Alt + B を設定する場合
Alt にチェックを入れる
キー欄をスクロールして Alt+B をクリック
- 割付 を押下します。
- 機能に割り当てられているキー に Alt+B が、 機能に割り当てられている機能 に make html が表示されている事を確認し OK をクリックします。
プロジェクト 内のreSTファイルをサクラエディタで開き、おもむろに割付したキー(例では Alt+B )を押しましょう。
make html の結果がポップアップされ、編集している reSTファイル のhtmlがWebブラウザで開かれれば成功です。
マクロの中身
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | Option Explicit
Dim objWshShell
Dim objFso
Dim objFile
Dim inFileName
Dim objParentFolder
Dim parentfolder
Dim makebat
Dim objFolder
Dim bat
Dim WshScriptExec
Set objWshShell = CreateObject("WScript.Shell")
Set objFso = CreateObject("Scripting.FileSystemObject")
Function getParentFolder()
inFileName = ExpandParameter("$F")
If objFso.FileExists(inFileName) = True Then
Set objFile = objFso.GetFile(inFileName)
getParentFolder = objFile.ParentFolder
End If
End Function
Function existsMakebat(parentfolder)
bat = true
Do until (bat = false)
makebat = parentfolder & "\make.bat"
set objFolder = objFso.GetFolder(parentfolder)
If objFso.FileExists(makebat) Then
objWshShell.CurrentDirectory = parentfolder
existsMakebat = makebat
exit function
ElseIf objFolder.IsRootFolder Then
existsMakebat = false
bat = false
exit function
Else
parentfolder = objFolder.ParentFolder
End If
loop
End Function
Function main()
parentfolder = getParentFolder
makebat = existsMakebat(parentfolder)
if makebat = false Then
msgbox "makeに失敗しました", 16, "Result"
Elseif makebat = null Then
msgbox "makeに失敗しました", 16, "Result"
Else
Set WshScriptExec = objWshShell.Exec("make.bat html")
Do While (WshScriptExec.Status = 0)
objWshShell.run "ping -n 2 localhost", 0, True
loop
objWshShell.run("_build\html\" & ExpandParameter("$g") & ".html")
msgbox WshScriptExec.StdOut.ReadAll, 64, "Result"
End If
End Function
main
Set objWshShell = nothing
Set objFso = nothing
Set objFile = nothing
Set objFolder = nothing
Set WshScriptExec = nothing
|
さ～て、明日のSphinxアドベントカレンダーは？
- 明日は @grimroseさん が 担当 です。手順書を作成した時の過程を書かれるそうです。楽しみですね！