新型コロナ太りには位置ゲーが効く？ 
|
|
|
はなすこと
- Sphinxとは
- なぜSphinx？
- Sphinx+Jupyterの事例
Sphinxとは
Sphinxとどりらん 
Sphinxの用途
- Quantopian 日本語翻訳プロジェクト
- 執筆
- 雑誌の記事（後述）
- 技術書2冊（詳細は懇親会で）
Sphinxで書いた雑誌
なぜSphinx？
Q1: ツールやフレームワークを選ぶ基準
- 設計周りが優れている
- なじみのある言語で作られている
- ドキュメントが充実している
- 日本語の情報が充実している
- 修正や更新が頻繁に行われている
- その他
なぜSphinx？
困ったときに助けてくれる人がすぐ近くにいる
- 開発者(コミッタ/メンテナ)
- コミュニティ
「近い」とは
- 言語(母国語)
- 知り合い
- コミュニケーションしている
- チャット
- SNS
- etc
質問する上でのハードル
- 言葉の壁(英語)
- コミュニケーションの距離
- 知らない・会ったことない・話したことない
- 前提知識
Sphinx-Users.jp（Sphinxの日本ユーザ会）
- Sphinxのことは日本語で気軽に質問/相談できる
- 中の人（コミッタ・メンテナ）も日本人
- 日本語ができる = 世界一恵まれているSphinxユーザになれる
質問する(できる)ことで得られる利点
- 自己解決以上のソリューション
- 「こうしたほうがうまく」みたいな発見/アドバイス
- いずれ詰まったときにきける安心感
- とりあえずやってみてわからなかったらきけばいいや
OSSへの貢献
Q2: OSSへ貢献したい？
- している
- したいけどハードルを感じる
Q3: OSSの貢献方法
- PR
- issue
- その他
Q4: OSS貢献の際のハードル
- 技術的なスキル
- 英語のコミュニケーション
- OSSやプロジェクトごとの文化の理解
Sphinxに貢献したい
- 日頃からお世話になっている
- コミッターとの距離が近い
- コードを修正するほどの技術力はない
Sphinx-Users.jpの活動に参加する
- イベントに参加
- Sphinx+翻訳 Hack-a-thon
- SphinxCon JP
- 定期総会
- ハンズオン
- Sphinx-Users.jpのサイト運営に協力する
- Slackで質問する
- 自分がききたいことは他の人もききたいことかも
テストユーザとしての貢献
- 最新のバージョンを使う
- ベータ版を使う
- さまざまなプラットフォームで使う
得た知見を共有する
- SNS
- ブログ
- イベント(トークやLTなど) <- イマココ
どりらんでもできたこと
- Windows固有のissueの再現/テスト 6813
- issue対応はSlackだとカジュアルにできる
- Dockerイメージ
- Slackに質問して得た知見をQiitaに共有
- SphinxCon JPでトーク
まとめ
- 助けてくれる人がいる -> ツールを使う大きな理由となる
- 日本語ができる -> 世界一恵まれているSphinxユーザ
- Sphinx-Users.jpにJoinしよう
- コード書けなくても、さまざまな方法でSphinxに貢献できる
Sphinxで技術書を書く
よくあるプログラミング解説の構成
print関数は文字列を出力します。
print("hello world")
hello world
はいできました。
必要な要件
- 解説
- コードの内容
- コードの実行結果
問題点
- コードのエラーに気づかない
- 実行結果の間違いに気づかない
- そもそもコードと結果を原稿に転記するのが手間
Jupyterで完結
Jupyterで原稿書けたら幸せになれそう
- コードのエラーに気づかない
間違ったらエラーがでる
- 実行結果の間違いに気づかない
- 実行結果がそのまま原稿になる
- そもそも原稿に転記するのが手間
- Notebookがそのまま原稿になる
Jupyterで原稿書いたものをSphinxで書籍化できないかな… 
nbsphinx
- Sphinxの拡張機能
- JupyterのNotebookをHTMLやLaTeXにビルドできる
- 数式やグラフもできる
- 基本的な使い方はSphinxと同じ
nbsphinxでドキュメントを作る手順
インストール
pip install jupyter nbsphinx
プロジェクトを作成
sphinx-quickstart -q -p nbsample -a nbauther -l ja --sep
source/conf.py
下記を追記
extensions = [
'nbsphinx',
'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']
Jupyter原稿を書く
source/sample.ipynb
Jupyterで記述できるマークアップ言語
- HTML
- GitHub Flavored Markdown(GFM)
- LaTeX
- reStructuredText
Jupyter NotebookでreSTセルにする方法
JupyterLabでreSTセルにする方法
toctreeにNotebookを追加
拡張子は含めない
source/index.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
sample
ビルド
make html
サンプルプロジェクト
Jupyterをドキュメント化すると
- Notebook資産を有効活用
- 構造/階層化されたドキュメント
- 検索できる
- 環境構築不要
まとめ
- JupyterとSphinxでプログラミングのドキュメントが捗る
- nbsphinxで簡単にJupyterでドキュメントが作れる
- Jupyterの資産を有効活用
SphinxとOSSと私 みんなのPython勉強会#58 2020-06-10 driller @patraqushe
{"metaMigratedAt":"2023-06-15T08:30:27.093Z","metaMigratedFrom":"YAML","title":"SphinxとOSSと私","breaks":true,"description":"みんなのPython勉強会#58","lang":"ja-jp","slideOptions":"{\"allottedMinutes\":20,\"parallaxBackgroundImage\":\"https://www.sphinx-doc.org/ja/master/_static/headerbg.png\"}","contributors":"[{\"id\":\"c8293db1-2634-4fca-a1fe-de631ba868a8\",\"add\":9175,\"del\":1372}]"}