Sphinx Advent Calendar 2012 (全部俺)

初心者がどのようにSphinxを使ってきたかという記録

第11日目 Sphinxドキュメントを編集する その8

昨日は外部リンクの張り方を説明しました。今日は プロジェクト 内へのリンクを説明します。

ドキュメントへのリンク

  • 他のドキュメント( rstファイル )へリンクを張りたい時は :doc: というマークアップをします。

    記述例:

    昨日のタイトルは :doc:`../10/write_rest7` です。一昨日は :doc:`toctree <../09/write_rest6>` について説明しましたね。
    

    このように表示されます。

    昨日のタイトルは 第10日目 Sphinxドキュメントを編集する その7 です。一昨日は toctree について説明しましたね。

  • ファイルへのパスは拡張子が不要です。

  • ファイルパスはドキュメントの起点となる index.rst/ (ルート) とした絶対パスか、相対パスで記述して下さい。

本家 Sphinx Advent Calendar 2012 10日目 ~サクラエディタから make html~

9日目の 波田野さん ( @tcsh )から受け取りました。

ドキュメント作成の歴史を紐解きながら、ドキュメントの構造化~システマティックなドキュメント作成への期待を語られていて興味深く感じました。

さて 本家 Sphinx Advent Calendar 2012 の10日目です。全部俺版とは別に投稿したいと思います。

サクラエディタとマクロ

最近では VimSublime Text 2Emacs だとかが流行っているらしいですが、Windows使ってるなら サクラエディタ でしょう。

仕事柄、色々な現場に入るのですが、どこでも サクラエディタ は必ず使われています。かくいう私も10年程 サクラエディタ を使っておりました。 第3日目 Sphinxドキュメントを書く道具 も参照して頂けると幸いです。

この サクラエディタ 、マクロが PPA と WSHが使えます。 詳しくは こちらへ

makeからブラウザ確認までを1動作で

  • タイトルの通りです。サクラエディタで編集する際に 編集 -> make html -> ブラウザを起動して確認 ..... というサイクルの手間を少し省く事ができます。

使い方

  1. これ をダウンロードし、任意のディレクトリに配置します。

    例:

    C:\tools\Editor\macro\build_and_browsing.vbs
  2. 設定 -> 共通設定 -> マクロ タブにて マクロ一覧 にマクロを配置したディレクトリを指定します。

    ../../../_images/make_on_sakura01.png
  3. マクロの登録一覧の空欄の部分を選択します。初めて登録するならば 0 を選択しましょう。

    ../../../_images/make_on_sakura03.png
  4. 名前 に任意の名前を付けます。とりあえず make html としておきましょう。

    ../../../_images/make_on_sakura04.png
  5. File にてドロップダウンメニューからマクロのファイルを選択します。

    ../../../_images/make_on_sakura05.png
  6. 設定 をクリックします。

    ../../../_images/make_on_sakura06.png
  7. マクロ一覧0make html が登録された事を確認します。

    ../../../_images/make_on_sakura07.png
  8. キー割り当て タブをクリックします。

    ../../../_images/make_on_sakura071.png
  9. 種別外部マクロ にします。

    ../../../_images/make_on_sakura08.png
  10. make html をクリックします。

../../../_images/make_on_sakura09.png
  1. 任意のキーを割付して下さい。

    Alt + B を設定する場合

    1. Alt にチェックを入れる

      ../../../_images/make_on_sakura10.png
    2. キー欄をスクロールして Alt+B をクリック

    ../../../_images/make_on_sakura11.png
    1. 割付 を押下します。
    ../../../_images/make_on_sakura12.png
    1. 機能に割り当てられているキーAlt+B が、 機能に割り当てられている機能make html が表示されている事を確認し OK をクリックします。
    ../../../_images/make_on_sakura13.png
  2. プロジェクト 内のreSTファイルをサクラエディタで開き、おもむろに割付したキー(例では Alt+B )を押しましょう。

  3. make html の結果がポップアップされ、編集している reSTファイル のhtmlがWebブラウザで開かれれば成功です。

../../../_images/make_on_sakura14.png

マクロの中身

 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さん担当 です。手順書を作成した時の過程を書かれるそうです。楽しみですね!