# SphinxとOSSと私 みんなのPython勉強会#58 2020-06-10 driller[@patraqushe](https://twitter.com/patraqushe) --- ### 誰？ - [どりらん](https://twitter.com/patraqushe)  - [fin-py](https://fin-py.connpass.com) - ぼっち会社経営 - 在宅勤務歴10年 - 非エンジニア - よく歩いてます<a href="https://www.dragonquest.jp/walk/"><img src="https://pbs.twimg.com/profile_images/1169446429720363008/EAQDTMsd.png" width=35 height=35></a> ---- ### 新型コロナ太りには位置ゲーが効く？ :earth_asia: <table> <tr> <td> <li>歩くほど(ゲームのキャラが)強くなる</li> <li>寝付きがよくなる</li> <li>熱中症に注意</li> </td> <td> <img src="https://i.imgur.com/gWEBzK1.png"></img> </td> </tr> </table> ---- ### もくもく会やってます :headphones:  https://fin-py.connpass.com/event/177337/ --- ## はなすこと 1. Sphinxとは 1. なぜSphinx？ 1. Sphinx+Jupyterの事例 --- ## Sphinxとは {%slideshare TakeshiKomiya/sphinx-2012-pyconjp-sphinxconjp %} ---- ### [Projects using Sphinx](https://www.sphinx-doc.org/en/master/examples.html) - [Python](https://docs.python.org/) - [Linux kernel](https://www.kernel.org/doc/html/latest/index.html) - [NumPy](https://docs.scipy.org/doc/numpy/reference/), [Scipy](https://docs.scipy.org/doc/scipy/refrence/), [pandas](https://pandas.pydata.org/pandas-docs/stable/) ... - [Django](https://docs.djangoproject.com/), [Flask](https://flask.palletsprojects.com/) ... ---- ### [Sphinxを使用して執筆された書籍](https://sphinx-users.jp/book_usage.html) - [Go言語による並行処理](https://www.oreilly.co.jp/books/9784873118468/) - [Pythonプロフェッショナルプログラミング第3版](https://www.shuwasystem.co.jp/products/7980html/5382.html) - [独学プログラマー](https://shop.nikkeibp.co.jp/front/commodity/0000/C92270/) - [仕事ではじめる機械学習](https://www.oreilly.co.jp/books/9784873118253/) - [Sphinxをはじめよう第2版](https://www.oreilly.co.jp/books/9784873118192/) - [Pythonスタートブック［増補改訂版］](https://gihyo.jp/book/2018/978-4-7741-9643-5) --- ## Sphinxとどりらん  ---- ### Sphinxの用途 - [Quantopian 日本語翻訳プロジェクト](https://github.com/tokyoquantopian/quantopian-doc-ja) - 原文: https://www.quantopian.com/docs/index - 執筆 - 雑誌の記事（後述） - 技術書2冊（詳細は懇親会で） ---- #### Quantopian Tutorial の翻訳ハッカソン  https://quantopian-tokyo.connpass.com/event/178141/ ---- ### Sphinxで書いた雑誌 [](https://gihyo.jp/magazine/SD/archive/2018/201802) [](https://gihyo.jp/book/2019/978-4-297-10396-5) [](https://gihyo.jp/magazine/SD/archive/2019/201904) [](https://gihyo.jp/magazine/SD/archive/2020/202002) ---- ## なぜSphinx？ ---- ### Q1: ツールやフレームワークを選ぶ基準 - [ ] 設計周りが優れている - [ ] なじみのある言語で作られている - [ ] ドキュメントが充実している - [ ] 日本語の情報が充実している - [ ] 修正や更新が頻繁に行われている - [ ] その他 ---- ### なぜSphinx？ 困ったときに助けてくれる人が**すぐ近くに**いる - 開発者(コミッタ/メンテナ) - コミュニティ ---- ### 「近い」とは - 言語(母国語) - 知り合い - コミュニケーションしている - チャット - SNS - etc ---- ### 質問する上でのハードル - 言葉の壁(英語) - コミュニケーションの距離 - 知らない・会ったことない・話したことない - 前提知識 ---- ### Sphinx-Users.jp（Sphinxの日本ユーザ会） - Sphinxのことは日本語で気軽に質問/相談できる - 中の人（コミッタ・メンテナ）も日本人 - **日本語ができる = 世界一恵まれているSphinxユーザになれる** ---- ### 質問する(できる)ことで得られる利点 - 自己解決以上のソリューション - 「こうしたほうがうまく」みたいな発見/アドバイス - いずれ詰まったときにきける安心感 - とりあえずやってみてわからなかったらきけばいいや ---- ### Sphinx-Users.jpに中の人がいる https://github.com/orgs/sphinx-doc/people [](https://twitter.com/tk0miya/) [](https://twitter.com/shimizukawa) ---- ### Sphinx-Users.jpの活動 - [Webサイト](https://sphinx-users.jp/) - Sphinx+翻訳 Hack-a-thon - ハンズオン - カンファレンス（SphinxCon JP） - [Slack](https://sphinx-users.jp/howtojoin.html#slack) - [Twitter](https://twitter.com/sphinxjp) - 総会 ---- ### Sphinx+翻訳 Hack-a-thon 遠方で参加できなかった人はいまがチャンス :exclamation:  https://sphinxjp.connpass.com/event/177521/ ---- ## OSSへの貢献 --- ### Q2: OSSへ貢献したい？ - [ ] している - [ ] したいけどハードルを感じる ---- ### Q3: OSSの貢献方法 - [ ] PR - [ ] issue - [ ] その他 ---- ### Q4: OSS貢献の際のハードル - [ ] 技術的なスキル - [ ] 英語のコミュニケーション - [ ] OSSやプロジェクトごとの文化の理解 ---- ### Sphinxに貢献したい - 日頃からお世話になっている - コミッターとの距離が近い - コードを修正するほどの技術力はない ---- ### Sphinx-Users.jpの活動に参加する - イベントに参加 - Sphinx+翻訳 Hack-a-thon - SphinxCon JP - 定期総会 - ハンズオン - [Sphinx-Users.jp](https://sphinx-users.jp)のサイト運営に協力する - [Source repository](https://github.com/sphinxjp/sphinx-users.jp) - [Slack](https://sphinx-users.jp/howtojoin.html#slack)で質問する - 自分がききたいことは他の人もききたいことかも ---- ### テストユーザとしての貢献 - 最新のバージョンを使う - ベータ版を使う - さまざまなプラットフォームで使う ---- ### 得た知見を共有する - SNS - ブログ - イベント(トークやLTなど) <- イマココ ---- ### どりらんでもできたこと - Windows固有のissueの再現/テスト [6813](https://github.com/sphinx-doc/sphinx/issues/6813) - issue対応はSlackだとカジュアルにできる - Dockerイメージ - [Docker Hub](https://hub.docker.com/orgs/sphinxdoc) - Slackに質問して得た知見を[Qiita](https://qiita.com/driller/items/31c1ff4d0bf5813f624f)に共有 - [SphinxCon JPでトーク](https://sphinxjp.connpass.com/event/154759/) ---- ## まとめ - 助けてくれる人がいる -> ツールを使う大きな理由となる - 日本語ができる -> 世界一恵まれているSphinxユーザ - Sphinx-Users.jpにJoinしよう - コード書けなくても、さまざまな方法でSphinxに貢献できる --- ## Sphinxで技術書を書く ---- ### よくあるプログラミング解説の構成 :::info print関数は文字列を出力します。 ```python print("hello world") ``` ``` hello world ``` はいできました。 ::: ---- ### 必要な要件 - 解説 - コードの内容 - コードの実行結果 ---- ### 問題点 - コードのエラーに気づかない - 実行結果の間違いに気づかない - そもそもコードと結果を原稿に転記するのが手間 ---- ### Jupyterで完結  ---- ### Jupyterで原稿書けたら幸せになれそう - コードのエラーに気づかない - :heavy_check_mark: 間違ったらエラーがでる - 実行結果の間違いに気づかない - :heavy_check_mark: 実行結果がそのまま原稿になる - そもそも原稿に転記するのが手間 - :heavy_check_mark: Notebookがそのまま原稿になる ---- Jupyterで原稿書いたものをSphinxで書籍化できないかな... :thinking_face: ---- ### [nbsphinx](https://nbsphinx.readthedocs.io/) - Sphinxの拡張機能 - JupyterのNotebookをHTMLやLaTeXにビルドできる - 数式やグラフもできる - 基本的な使い方はSphinxと同じ ---- ### nbsphinxでドキュメントを作る手順 ---- #### インストール ```bash pip install jupyter nbsphinx ``` ---- #### プロジェクトを作成 ```bash sphinx-quickstart -q -p nbsample -a nbauther -l ja --sep ``` ---- #### source/conf.py 下記を追記 ```python extensions = [ 'nbsphinx', 'sphinx.ext.mathjax', ] exclude_patterns = ['_build', '**.ipynb_checkpoints'] ``` ---- #### Jupyter原稿を書く `source/sample.ipynb`  ---- ### 軽量マークアップ言語 - [HTML]() - [Markdown](https://daringfireball.net/projects/markdown/) - [CommonMark](https://commonmark.org) - [GitHub Flavored Markdown(GFM)](https://github.github.com/gfm/) - [LaTeX](https://www.latex-project.org) - [reStructuredText](https://docutils.sourceforge.io/rst.html) - [Asciidoc](https://asciidoc.org) ---- ### Jupyterで記述できるマークアップ言語 - HTML - GitHub Flavored Markdown(GFM) - LaTeX - reStructuredText ---- #### Jupyter NotebookでreSTセルにする方法  ---- #### JupyterLabでreSTセルにする方法  ---- #### toctreeにNotebookを追加 拡張子は含めない `source/index.rst` ```rst .. toctree:: :maxdepth: 2 :caption: Contents: sample ``` ---- #### ビルド ```bash make html ```  ---- サンプルプロジェクト https://github.com/drillan/SphinxConJP2019 ---- #### Jupyterをドキュメント化すると - Notebook資産を有効活用 - 構造/階層化されたドキュメント - 検索できる - 環境構築不要 ---- ## まとめ - JupyterとSphinxでプログラミングのドキュメントが捗る - nbsphinxで簡単にJupyterでドキュメントが作れる - Jupyterの資産を有効活用 ---