acokikoy's notes

{"勉強中":"Python","注目":"Shopify","LOVE♡":["ABARTH595","TA-GG9","Ukulele","Movable Type","ガーナ ミルクチョコレート"]} なWebディレクター

トップ > Python > イベント参加ログ》みんなのPython勉強会#58 @2020年6月10日（水）19:00〜21:00 オンライン開催

イベント参加ログ》みんなのPython勉強会#58 @2020年6月10日（水）19:00〜21:00 オンライン開催

Python イベント・勉強会 開発環境・ツール

みんなのPython勉強会#58 の聴講メモ。
YouTubeライブ配信によるオンライン開催で、テーマは「Python製ドキュメント生成ツールSphinx丸わかり」。
当日誰かのtweetだかslackだかで気づいて飛び入り聴講した。予想を越える面白さで参加して良かった。

startpython.connpass.com

Twitter #stapy%20lang%3Aja%20until%3A2020-06-15%20since%3A2020-06-10&src=typed_query)

  • どりらん@patraqusheさん

    • 非エンジニア
    • fin-py - connpass
    • Sphinxとは
      • プレーンテキスト
      • reST restructured text（Wiki記法みたいなもん？）
      • Sphinxのよいところ
        • ❇️ソースがテキストなのでバージョン管理できる
        • 拡張視野類
        • toctreeベース（目次:文書構造の階層管理）
      • Sphinxで書かれたもの
      • どりらんさんとSphinx
        • Quantopian日本語翻訳プロジェクト
        • 執筆
      • Sphinx-Users.jp 日本のSphinxユーザ会（世界的にも強力なユーザ会）
        • ❇️質問することで得られる利点
          • 自己解決以上のソリューションが得られる
          • いずれ詰まった時にきける安心感
        • Slackで質問
        • Sphinx翻訳ハッカソン → 今だけリモート開催
    • OSSに貢献したい？
      • テストユーザとしての貢献
    • 技術書書く時に使っている

  • 吉政忠志さん

    • この前BPStudy#152 に登壇されてた「ITエンジニアのための企画力と企画書の教科書」の人
    • PythonED ・・Pythonicを理解した人材が育成されるよう
    • Python3エンジニア認定データ分析試験（PythonCDA） データ分析の基礎や方法を問う試験
    • 基礎試験の上位試験、データ分析の上位試験を企画中

  • 波田野裕一@tcshさん

    • 発表資料: https://twitter.com/tcsh/status/1270694581357604866
    • 以前: 手順書をHTMLやxmlで書いたりしていた
    • Sphinx
    • JAWS-UG CLI専門支部
    • AWS CLI公式リファレンスはSphinxでビルドされている
    • ドキュメント作成を人と機械で分担する
      • reSTructured Text
      • "人にしか書けない部分"を人が書く
      • 「機械がかけるところを機械に書かせる」考え方だと人の工数は減らない
      • "人が書かなくても良いところ"を機械に書かせる
    • 機械に書かせる
      • ヒアドキュメント
      • catコマンド
      • sedコマンド
    • Sphinxの重要な機能。この3つを意識的に使うのがコツ。
      • インクルード機能
      • 置換機能
      • toctree（文書構造を決める）
    • どう構造化するかを常に考える
      • reSTで書く
      • 何を作りたいか全体像を考える
      • 変化が少なく寿命が長い文書にこそ工数をかけるべき
      • 陳腐化が速い文書は機械に書かせる　（週報とか）
      • ❇️Sphinxでドキュメントを書いていると脳内も構造化されていく

  • @tk0miyaさん

    • 発表資料: https://twitter.com/tk0miya/status/1270677674646630400
    • 青プジョー(206?)の人。Sphinx
    • Sphinxはドキュメントビルダーの1つ
    • 主な機能
      • 見た目が整う（イイ感じのテーマで）
      • クロスリファレンス機能
      • 形式変換
        • HTML, PDF, text, EPUBなどなど
      • 拡張パッケージ
      • 使い道
        • Webページ、リファレンス、書籍
    • コードからドキュメント生成
      • プログラムを書き換えるとリファレンスも自動更新されて欲しい → Sphinx
      • autodoc拡張（モジュール単位）
        • Pythonモジュールを原稿として扱う。
        • クラス構造や関数の引数情報, docstring、型アノテーションを読み取ってドキュメント化
        • conf.py でautodoc有効化
        • docstringに引数の説明を書く
          • :param x: 数値1
          • #: 円周率 ・・・classのメンバ変数
        • 型アノテーション def sum(self, x: int, y:int) -> int:
      • intersphinxで他のSphinxドキュメントへのリンクが貼れる（Python公式とかnumpyとかへ）
      • 全体的な説明をドキュメントに書いておく
      • ❇️プログラムが大きくなってきたら autosummary, apidocなどの拡張（プログラム単位でのドキュメント化）
    • Sphinx-Users.jp — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
    • 個人スポンサー