wired raven

文字通りの日記。主に思ったことやガジェットについて

ドキュメント生成ツールを求めて

動機

  • Markdownで書けるといいな
  • Excelなんて使ってられるか

候補

  • Sphinx
    • 拡張を導入してMarkdown形式にも対応できる、らしい。環境構築で躓きまくっている
  • MkDocs
    • 標準でMarkdown形式に対応している。作成、生成ともに楽
  • Jupyter Notebook
    • これはコーディング環境だけど、ドキュメントも書けるそうで

MkDocsを試す

大まかな流れ

  1. Pythonインストール
  2. MkDocsインストール
    • pip install mkdocs
  3. テーマ「material」インストール
    • pip install mkdocs-material
  4. プロジェクトフォルダの作成
    • お好みの場所でmkdocs new プロジェクト名
  5. 実際に書く
    • Markdown形式でファイルを作成
    • プロジェクト直下に作成するとヘッダに追加される
    • docsに入れると特にはなさげ
  6. HTMLを生成する
    • プロジェクトのフォルダでmkdocs build

これ覚えておこう

自動生成

  • mkdocs serve
  • http://127.0.0.1:8000から内容が確認できる

mkdocs.yml

site_name: My Docs

theme:
  name: 'material'
  language: 'ja'

日本語検索にも対応しているというこのパワーよ。