読者です 読者をやめる 読者になる 読者になる

どらちゃんのポッケ

R・統計・技術メモなど勉強ログ置き場

markdown形式のファイルをSphinxっぽく出力できるParmを試す

Parmをためす

インストール

  • pythonとpipが入っていれば簡単
  • 当然、pythonの環境ぐらい入ってますよね?笑

      sudo pip install par
      sudo pip install parm
    
  • 以上。簡単。

まずは、使ってみる

  1. 作成先のディレクトリにフォルダを作成する。 今回はデスクトップに作成してみる

     cd Desktop/
     mkdir parmTest
    
  2. ディレクトリに移動

     cd parmTest/
    
  3. テンプレートを生成する

     parm init
    
  4. 質問に答えて、テンプレートの初期設定をしていく。

     //プロジェクトの名前を決める
     Project name [Parm]: myFirstParm
    
     //Copyrightを決める
     Copyright information [2013, Limodou]: 2014,michi
    
     //バージョンを指定
     Version [1.1]:
    
     //CSSのテーマを設定
     Choice theme (bootstrap, semantic) [semantic]:
    
     //Disqusにアップする場合のアカウント名?
     Disqus account name []:
    
     //検索ボックスを入れるか
     If you want to add search input(Y/n)[Y]:
    
     //検索でつかうドメイン名
     Domain name used for search []:
    
     //ファイル生成
     {'template_dirs': 'templates', 'domain': '', 'copyright': '2014,michi', 'search': True, 'project': 'myFirstParm', 'theme': 'semantic', 'version': '1.1', 'disqus': ''}
     Copy theme/semantic/templates to ./templates
     Copy init files [index.md*](Y/n)[Y]:
     Copy templates/env/index.md to ./index.md
     Copy templates/env/introduction.md to ./introduction.md
     Copy templates/env/exclude.txt to ./exclude.txt
    
  5. 本番のHTML生成

     Parm make
    
  6. みてみる f:id:sleeping_micchi:20140124022952p:plain

  7. ちなみに、ソースはこんな感じ

      Parm Introduction
      ==================
    
      What's this
      ------------
    
      This documention is just for demo, you need to replace it with you real docs.
    

自分でも作ってみる

mkdir parmTest2
cd parmTest2/
parm init

Project name [Parm]: my second parm
Copyright information [2013, Limodou]: 2014,michi
Version [1.1]: 0.1
Choice theme (bootstrap, semantic) [semantic]:
Disqus account name []:
If you want to add search input(Y/n)[Y]:
Domain name used for search []:
{'template_dirs': 'templates', 'domain': '', 'copyright': '2014,michi', 'search': True, 'project': 'my second parm', 'theme': 'semantic', 'version': '0.1', 'disqus': ''}
Copy theme/semantic/templates to ./templates
Copy init files [index.md*](Y/n)[Y]:
Copy templates/env/index.md to ./index.md
Copy templates/env/introduction.md to ./introduction.md
Copy templates/env/exclude.txt to ./exclude.txt
  • こんな感じで作りました。

    • フォルダはこんな感じ生成される。 f:id:sleeping_micchi:20140124023204p:plain
  • index.mdに含めるmarkdownファイルの一覧を記述する

      ## fitbitって良いよ!
      {% toc max_depth=1 %}
      fitbit.md
      {% endtoc %}
      ## Parmをためす
      {% toc max_depth=1 %}
      parm.md
      {% endtoc %}
    
  • makeする。makeした後のフォルダは下記の通り

生成されるHTMLをみてみる

  • フォルダ構造 f:id:sleeping_micchi:20140124023208p:plain

  • index f:id:sleeping_micchi:20140124022952p:plain

  • 中身

    • コードもいい感じにシンタックスハイライトされてる f:id:sleeping_micchi:20140124022946p:plain

ハマったこと

  • Bootstrapのテーマが動かない
    • bootstrapのテーマの方はあんまりいい感じに動かなかった・・・。
    • ドキュメントに下記のようにあったから、安定していないのだろう。

About theme¶

For 0.8 version, parm is already support two themes: bootstrap, semantic. But I prefer the semantic, because I made more care about it. If you want to change the theme, you can just change :

  • #を使って見出しを作っていると、markdownファイルからHTMLへの変換に失敗する

    • markdownファイルの見出しの記法は#====があるが、#だとコケた
    • 下記のようなエラーになってしまった・・・
      • Error: Heading 1 not found in file parm.md
      • ERROR:root:File parm.md can't be found, will be skipped
    • ====こっちの記法で書き直したら動いた。んー。
  • 左ペインの項目は------で見出しを付けた項目になる

  • 検索窓がうまいこと動かない・・・

感想

  • やっぱり、SphinxのreSTよりもmarkdownの方が扱いやすいので、parmを使っていこうかと思う。
    • markdownの方がエディタも豊富だしね
  • ちょうどSphinxを使い始めようかと思ったが、やめた!笑